How to setup unite cms for local development or on a production server

In this article i’m gonna show how to setup unite cms for local development or for production. As there are a lot of different setup possiblities out there (OS, Webserver etc.), i will show only some of them and will link to external tutorials or docs from time to time. In the first part i will show how to setup a local development environment for building your own app based on unite-cms. (fe. if you want to build a custom app based on unite cms and need some additional functionality), in the second part how to setup an development environment to contribute to unite cms core and help us to build the greatest headless cms ever. Finally i will show an example how to configure unite cms on a production server. Currently unite cms requires only a PHP version >= 7.1, Composer and MySQL >= 5.7.9.


Setup a local development environment to build something great based on unite cms

Step 1:

Install PHP, MySQL and Composer according to your OS. Make sure your setup can run symfony 4 framework, everything is explained very well in the symfony docs (see https://symfony.com/doc/current/setup.html). You can use the PHP’s built in webserver (https://symfony.com/doc/current/setup/built_in_web_server.html) or setup an apache or nginx webserver on your machine (https://symfony.com/doc/current/setup/web_server_configuration.html).

Step 2:

composer create-project unite-cms/standard unitecms --stability dev
cd unitecms
bin/console doctrine:schema:update --force

On composer install (and update) you will be asked to set all required environment (dotenv) variables.

Finally access unite cms through your local apache or nginx webserver or start the PHP’s built in development server:

bin/console serve:run

After unite cms was successfully installed you can create a Platform Administrator and your first organization with the following commands:

bin/console unite:user:create
bin/console unite:organization:create

Setup a local development environment for contributing to unite cms core

At first fork unite-cms repository https://github.com/unite-cms/unite-cms.

There are 2 setup possibilities:

Standard Setup:

Step 1:

Execute Step 1 from the example above.

Step 2:

Clone your (forked) repo to your desired place. (fe. /var/www)

cd /var/www
git clone https://github.com/[yourname]/unite-cms.git
cd unite-cms

Step 3:

Run composer install to fetch all required dependencies

composer install

Step 4:

Setup .env file and create mysql database

cp .env.dist .env

edit .env file and change it according to your needs


environment file

There is only one specific unite cms env variable
ROUTING_APPROACH=parameter

The default routing approach is by subdomain, so organizations will run under a subdomain (fe. https://org1.unite.test). For local development, i would recommend using “parameter” setting which will pass the organization as parameter (fe. https://unite.test/org1).

create the configured database

bin/console doctrine:database:create

A successful installation should look like the following screenshot

Finally access unite cms through your local apache or nginx webserver or start the PHP’s built in development server with:

bin/console serve:run

Now you should be ready to go, you can find the unite cms codebase in src folder. A platform administrator and your first organization can be created with the commands from the first example.

Docker Setup:

For this method, i’m assuming that you already have some knowledge of docker, for beginners, a good starting point is the docker documentation. (https://docs.docker.com/)

Step 1:

Install composer, docker and docker compose on you machine (https://www.docker.com) and make sure all commands do work fine.

Step 2:

Clone your (forked) repo to your desired place. (fe. /var/www)

cd /var/www
git clone https://github.com/[yourname]/unite-cms.git
cd unite-cms

Step 3:

Setup .env file and create mysql database

cp .env.docker .env

edit .env file and change it according to your needs

The SOURCE_DIR variable is only needed on OSX for Performance reasons.
See Docker readme file for detailed instructions: https://github.com/unite-cms/unite-cms/tree/master/.docker

Step 4:

Run composer install to update the codebase with all required dependencies

composer install

Step 5:

edit docker-compose.yml file and change it to your desires

docker-compose.yml

This example shows a full blown setup with unite cms, a MySql Container, minio S3 and mailcatcher. Be sure that all used ports are free and available on your machine! In this example i’m using a ubuntu linux box, if you are running OSX, please check the readme under https://github.com/unite-cms/unite-cms/tree/master/.docker for a better performance with docker.

Step 6:

docker-compose build (this can take some time)
docker-compose up -d
docker ps (check if all containers are up and running)
On first startup, you have to run 2 commands to initialize assets and database:
docker exec unitecms-web /app/unite-cms/bin/console assets:install
docker exec unitecms-web /app/unite-cms/bin/console doctrine:schema:update --force

docker commands

All containers should be running and available, for this example check:
http://unite.test:8080 (unite cms)
http://unite.test:9000 (minio S3)
http://unite.test:1080 (mailcatcher)

Great, isn’t it? Simply start to edit files in src folder!


Setup a unite cms production environment

In this example, i will show how to setup unite cms on a root server or managed server with ssh access. Maybe a tutorial for some cloud hosting providers (AWS, google cloud, openshift) will follow in the future.

Step 1:

Execute Step 1 of the standard setup example above

Note: On a managed server with ssh access the commands should work as well. If you don’t have access to apache vhost configuration you might need the following composer package, which will install a .htaccess to hande the routing part.

composer require symfony/apache-pack

Step 2:

Create the project in your desired place (fe. /var/www)

composer create-project unite-cms/standard unitecms --stability dev --no-dev --no-scripts
cd unitecms

Step 3:

Configure the Environment Variables. In a production environment, Environment variables should be set on the server level instead of using the .env file.

A good explanation can be found here (https://help.ubuntu.com/community/EnvironmentVariables).
The recommended and most secure way (especially if more apps are running on the same server) is using Session-wide environment variables for a specific user, fe. if your project is running with linux user “unite-cms”, configure the needed ENV vars for this user only.

Step 4:

run these commands to complete the installation:

bin/console assets:install --env=prod
bin/console doctrine:schema:update --force --env=prod
bin/console cache:clear --env=prod