1. Environment Setup

Goal

This tutorial guides you through the setup of a local installation of Cloudrexx. For a development setup follow this guide and then check out the "Next steps" at the end.

Install Prerequisites

Install GIT

Download GIT from here. Execute the installer and follow the instructions.

Install GIT using the package management of your distribution. For Debian based systems you may execute the following command:

sudo apt install git

Download and install GIT from here.

Install Docker

The automated setup of Cloudrexx relies heavily on Docker and Docker Compose. Docker version 1.14 and Docker Compose version 1.9 are minimal requirements. The following instructions will install a much newer version of both on your system:

Download Docker-Machine and install it.

Download Docker-Toolbox and install it.

Docker-Toolbox allows you to use Docker on systems without HyperV. Docker-Toolbox does this by using VirtualBox in the background. See this article for more information.

Install Docker CE and Docker Compose. Here's a summarizing command for lazy people on Ubuntu (on your own risk):

sudo apt update && sudo apt install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    software-properties-common \
 && curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - \
 && sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
 && sudo apt update \
 && sudo apt install -y docker.io \
 && sudo usermod -aG docker $USER \
 && sudo curl -L https://github.com/docker/compose/releases/download/1.18.0/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose \
 && sudo curl -L https://raw.githubusercontent.com/docker/compose/1.18.0/contrib/completion/bash/docker-compose -o /etc/bash_completion.d/docker-compose \
 && sudo chmod +x /usr/local/bin/docker-compose

Download Docker-Machine and install it.

If your Mac does not fullfill all requirements for Docker-Machine, you may want to use Docker Toolbox.

Navigate to your working directory

Open a console (press WIN+r, type "cmd" and hit return) and use the cd command to get to a new (/empty) folder. Optionally create a new folder using mkdir.

Alternatively you can use PowerShell. The process for PowerShell is the same as above, just type "powershell" instead of "cmd"

Open the terminal of your choice and use the cd command to get to a new (/empty) folder. Optionally create a new folder using mkdir.

Open a console (under "Applications" - "Utilities" you'll find "terminal") and use the cd command to get to a new (/empty) folder. Optionally create a new folder using mkdir.

Download, install and setup Cloudrexx environment

Make sure you shut down any service that is running on port 80 on your system before you proceed. Alternatively, use a different port for your environment.

Download https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx using your browser and save it to your working directory. Rename it to cx.bat. In the console execute the following command and follow the instructions:

cx env init

Invoking the script directly as "cx" works since Windows automatically searches for a file with the same name and a "executable extension" (like .exe, .bat, .com).

All other examples of calling the script will include "./" before "cx". If you use Windows CMD you will have to remove "./" before "cx" from all examples.

Execute the following command and follow the instructions:

wget -O cx.bat https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx; ./cx.bat env init

In PowerShell, the script needs to be called including its extension, since PowerShell can execute files independently of their extension.

Execute the following command and follow the instructions:

wget https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx || curl -O https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx && chmod +x cx && ./cx env init

Docker might ask you to share your drive. This is necessary on non-native execution of Docker so the containers can access your working directory.

Open your local installation in your browser

The command you just started pulls the necessary files from GitHub and DockerHub, configures Docker Compose, starts the Docker containers, loads the database and configures your Cloudrexx installation. The process is automated but the script might ask you a thing or two.

After the command completed, you should be able to open your local Cloudrexx installation in your browser using the following link: http://lvh.me. To access the database you may use http://lvh.me:8234.

These links work because lvh.me, including all possible sub-domains and even sub-sub-domains of it, point to 127.0.0.1 / localhost.

Now feel free to enjoy your own Cloudrexx installation. For more information on what the script did or what else it can do, please refer to the next two sections.

More information

The script you executed has started multiple docker containers for your installation:

The "web" container is directly bound to your machine's port 80 (by default). This way you can access the webserver directly using any URL pointing to your host.

Next steps

Virtual-host setup

If you will have multiple local installations you may want to execute the following command in order to allow a virtual-host setup:

./cx envs up

This shuts your environment down (in order to free the occupied port 80) and starts the reverse proxy that will handle the virtual hosts. Then your environment is automatically reconfigured as a virtual-host (since the proxy is running) and started again.Please note that the URL for phpMyAdmin will have changed after this (since direct access via port is no longer necessary/possible).

This will create the following setup for you:

Now the "clx-proxy" container is directly bound to your machine's port 80 (by default). You can directly access the "web" and "phpmyadmin" containers through the proxy.

Further reading

For more information about how the above works and what else the script can do, please refer to the wiki page of the CLI script.

Explore the available commands

Type the following command to get a list of all available commands:

./cx help

You can get a more detailed description of a specific command by adding the command as an argument to the help command. For example to get a detailed description of the "env" command type:

./cx help env

Some commands have sub-commands. If so, they also provide a description of the sub-command using the same principle. For example to get a detailed description of the "update" sub-command of the "env" command type:

./cx help env update

 

Usage examples

Use a different port / change other settings

If you want to change the used port or any other setting, you can use the following command to reconfigure your system:

./cx env config --interactive

Or you can call config directly with the desired values as arguments. For the available arguments refer to the output of:

./cx help env config

The same arguments can also be passed to ./cx env init to directly initialize your system with the desired configuration.

Something went wrong during "./cx env init"

If something went wrong during the initialisation of your environment you have the following options:

  • Delete all files and re-try: Simply delete all files in the folder (including hidden ones like the ".git" folder)
  • Retry init without GIT clone: This saves a lot of time if GIT clone was successful. This can be done by using the following command: ./cx env init --skip-source --skip-scripts

Contrexx 4

Since Contrexx 4 is part of the public GIT repository on GitHub, it can be installed as easily as:

./cx env init --source-branch=contrexx_4_0

Contrexx 3.0 - 3.2

Since Contrexx 3 is not part of the public GIT repository on GitHub you will have to specify another repository or download it manually:

If you have a repository already containing a Contrexx 3, you may use the following command:

./cx env init --source-repo=<your_repository_url>

Otherwise you may download and extract the source code by hand and then call the following command:

./cx env init --skip-source

Contrexx 2.x

Follow the steps for Contrexx 3.0.

Contrexx 1.x

These versions of Contrexx are currently untested with this script. It may or may not work (best option is to follow the steps for Contrexx 3.0).

Install from an official package using the web installer

In order to install from an official package or to test the web installer, you may follow these steps instead of the ones in the package's readme.

For official packages, these steps are necessary since the web installer creates some files which are otherwise missing.

  1. Download the package and extract the contents of the "CMS_FILES" folder to your working directory.
  2. Download or copy the "cx" script to your working directory (unless the package is version 5 or newer).
  3. Call ./cx env init --skip-source --skip-database.
  4. Use the following command to see the database configuration: ./cx env config --show
  5. Your environment should be up and accessing it using your browser should redirect you to the web installer. Follow the installer's instructions and when asked to, use the database configuration from the previous step.
  6. After the web installer is finished you should call ./cx env init --skip-source --skip-scripts --skip-database

Install from existing project source

The following guide assumes that there's an existing project in the current directory:

  1. Make sure you have a backup of the project.
  2. If the project is a copy of a live site, you may need to cleanup some directives in the .htaccess file. Some hostings require special directives to activate PHP. Additionally, some sites may use custom redirect rules. These directives and rewrite rules need to be removed.
  3. Create the directory installer/data. If it already exists, delete and re-create it. On MacOS or Linux you may do so using the following command: mkdir -p installer/data.
  4. Copy a complete database dump of your project into the file installer/data/contrexx_dump_structure.sql.
  5. Create the empty file installer/data/contrexx_dump_data.sql. On MacOS or Linux you may do so using the following command: touch installer/data/contrexx_dump_data.sql.
  6. Install the cx-script by downloading it from https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx and making it executable. On MacOS or Linux you may do so using the following command: wget https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx || curl -O https://raw.githubusercontent.com/Cloudrexx/cloudrexx/master/cx && chmod +x cx.
  7. Start the environment by executing ./cx env init --skip-source. If you use Windows without PowerShell or Subsystem for Linux the correct command is cx env init --skip-source.

If the installation is not working as expected you might be using the wrong version of PHP. Execute ./cx env config --show to see which PHP version is used. To change the version use ./cx env config --php-version=7.2 for PHP 7.2. After this you need to restart the environment using ./cx env restart.