Installation using docker

Duration: 15-30 minutes.

This tutorial has been tested on a fresh minimal install of Ubuntu server 20.04.

1. Install and Configure nginx

This is only required for a production environment. If you test on your local machine, you can skip this step.

sudo apt-get install nginx

Create the nginx conf file for your app. Replace <> with the domain of your project.

sudo touch /etc/nginx/sites-available/<>.conf

For example, if you plan to host your server at, use the following command:

sudo touch /etc/nginx/sites-available/

Put the following in your just created .conf file. Again, replace <> with the domain of your project

upstream lcprivate_docker {
        server localhost:9202;

server {
        listen 80;
        server_name <> www.<>;
        return 301 https://<>/$request_uri;

server {
        listen 443;
        server_name <> www.<>;

        client_max_body_size 50M;

        location / {
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection 'upgrade';
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_cache_bypass $http_upgrade;
                proxy_pass http://lcprivate_docker;


2. Install docker

Install docker and the docker-compose-utility

sudo apt-get install docker-compose

Start docker

sudo systemctl start docker

make docker start on boot

sudo systemctl enable docker

3. Get the Local Cosmos Private Server docker image

All docker commands have to be run as the superuser.

sudo docker pull

4. Configuration with docker-compose.yml

On your server, create a folder for your project.

sudo mkdir /opt/<my-project-name>

Create the file docker-compose.yml

cd /opt/<my-project-name>
sudo touch docker-compose.yml

Put the following content into docker-compose.yml. Replace <my-project-name> with the name of your project. Also Replace <db_username> and <db_password>. This will set your database credentials, so do not share these values openly.

Also replace <> with the domain you run your Localcosmos Private Server on. Do not forget the leading .. Finally, replace <APP_UID> with app_uid of your App. You find your app_uid in the App Kit on If you just want to run the Demo App on localhost, use treesofbavaria as the app_uid. You cannot run the Demo App on something else than localhost.

version: '3.3'

        container_name: '<my-project-name>'
        image: ''
        restart: always
        build: .
          - type: volume
            source: www
            target: /var/www/localcosmos/
          - type: volume
                source: database_config
                target: /etc/postgresql/
          - type: volume
            source: database_log
            target: /var/log/postgresql/
          - type: volume
            source: database_data
            target: /var/lib/postgresql/
          - 9202:8001
          - DATABASE_NAME=localcosmos
          - DB_USER=<db_username>
          - DB_PASSWORD=<db_password>
          - ALLOWED_HOSTS=localhost|<>
          - APP_UID=<APP_UID>
          - SERVE_APP_URL=/


Optionally, you can add email settings to the environment. This enables django to send email to you if an error occurs server-side.

- EMAIL_HOST=<email_host>
- EMAIL_PORT=<email_port>
- EMAIL_HOST_USER=<email_host_user>
- EMAIL_HOST_PASSWORD=<email_host_password>

Replace <email_host>, <email_port>, <email_host_user>, <email_host_password> with your parameters and set EMAIL_USE_TLS to 1 or 0.

5. Run the docker container

cd /opt/<my-project-name>
sudo docker-compose up -d

6. Enable nginx conf and reload nginx conf

First, add your nginx conf to sites-enabled. Replace <> with the name of you project.

sudo ln -s /etc/nginx/sites-available/<>.conf /etc/nginx/sites-enabled/

Now, reload your nginx conf with the following command.

sudo service nginx reload

After Installation, visit localhost:9202/server/control-panel/ or <>/server/control-panel/ and follow the on-screen instructions.

You now have your Local Cosmos Private Server up and running.

If you are on a local machine and want to test the Demo App, proceed to Installing the Demo App.