Installation

To get started quickly, follow the instructions below.

For a complete overview on building, development and deployment options checkout the Before You Start option.

Prerequisites

Docker is required to build the containers. Please install them according to the official documentation:

Docker

or install Docker Desktop:

Also make sure that you have GNU’s make installed on your system.

Note

Windows

You can use the make command with the GNU Make for Windows package. On newer windows systems, simply use winget install GnuWin32.Make and make it executable with set PATH=%PATH%;C:/Program Files (x86)/GnuWin32/bin.

make via Cygwin is not supported, because it is not compatible with nodejs (see common_errors).

Note

Debian/Ubuntu

You need to install the docker compose plugin with sudo update && sudo apt-get install docker-compose-plugin.

Build

Before building the containers, you can change the basic configuration in the .env.main file. To build the containers, run the following command:

$ make ENV=main build

This command will build the containers.

The application should be available at http://localhost:9090

Note

The credentials for the admin user can be also found in the .env file!

Nginx / Certbot

We recommend to use nginx as a reverse proxy for the application and Certbot to support SSL.

To install nginx and Certbot, run the following commands (adapted from this Implementation):

sudo chmod 666 /var/run/docker.sock

# Clone Project
sudo git clone https://github.com/wmnnd/nginx-certbot.git /srv/nginx-certbot
cd /srv/nginx-certbot

# Modify Configuration
sudo nano init-letsencrypt.sh
sudo nano data/nginx/app.conf

# Run Script for first generation process of the certificate
sudo ./init-letsencrypt.sh

# Run docker compose to generate all docker instances
sudo docker compose up -d

Now the ssl certificate should be available and will be renewed periodically.

Tip

In the file docker-compose.yml you can add additional volumes to the service nginx (e.g., ./data/nginx/html:/var/www/html) to make further html files available.

A sample configuration for nginx ./data/nginx/app.conf can look like this:

### This part is for certificate updates and SSL Page Redirection
server {
    listen 80;
    server_name <your domain>;
    server_tokens off;

    location ^~ /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    location / {
        return 301 https://$server_name$request_uri;
    }
}

# For main environment
server {
    listen 443 ssl;
    server_name <your domain>;
    server_tokens off;

    ssl_certificate /etc/letsencrypt/live/<your domain>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<your domain>/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        #proxy_redirect off
        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 Access-Control-Allow-Origin *;
        proxy_pass http://<docker ip>:<app port>/;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Warning

The IP-Address can change, if the docker network is newly created! Please adapt the ip address accordingly! A better way is to reload just the config with sudo docker compose restart.

Possible errors

Wrong make file

/bin/bash: /cygdrive/c/Program Files/nodejs/npm: No such file or directory
make: *** [backend/node_modules/.uptodate] Error 127

This is usually an error with the wrong make file installed with cygwin, which is not compatible with nodejs. Please install the GNU make for Windows as described above.

Further make sure that the path to the make executable is correctly set in the PATH variable. You can check which make is used with where make (under Windows).

Note

In case of doubt, you can uninstall the cygwin make with the installer package manager setup-x86_64.exe of Cygwin.