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!

Updating the Instance and Backing Up the Database

To apply updates from your development branch to your deployment branch:

cd /home/deployer/your_project_directory # go to deployer dir as su
git checkout project-XX-name # go to our project dir
git pull # pull the update from remote repo
git checkout deploy-XX-name # switch to project deploy branch
git merge project-XX-name # merge code
git push --set-upstream origin deploy-XX-name # push project deploy code to remote repo

Then, rebuild the instance:

docker ps | grep "your_keyword"  # Optional: locate container
make CONTAINER=your_container_name backup_db # back up the db container for this instance
cat .env # check out the config file, make sure everything still looks right
make build # update the instance

Now test the instance in the front end, the bug should be solved already.

Rebuilding only the Moodle RPC container

If you touch any code under utils/rpcs/moodleAPI/ run:

$ make rpc_moodle_build

This rebuilds the rpc_moodle image and restarts that service without affecting Postgres or the test-RPC container.

Preparing the Server and Access

Before starting deployment, prepare the following (Should be done several days in advance):

Request Admin Access: Contact your system administrator and request admin or root access to the target server. Include a supervisor or project lead for approval if necessary.
Register a Domain: Ask the system administrator to add a new A-record for your study domain. Provide the following details:
- Domain: your-desired-subdomain.institution-domain.tld
- IP Address: Public IP of the target machine
- Type: A-record

Note

Make sure that the DNS Entry is available outside of the TU Darmstadt (may need some time).

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

Once the A-record (Preparing the Server and Access) has been registered and propagated, and the script executed, the SSL certificate should now 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.

### This part is for certificate updates and SSL 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;
    }
}

# Main server block for application access via HTTPS
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_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 recreated! Please adapt the IP address in the config accordingly.

A better way is to reload just the configuration using:

docker compose restart

Now the service should be available at your configured domain. If it doesn’t appear to work in your browser, try accessing it in an incognito/private tab first.

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.