MORE Deployment: Docker

Running the MORE Platform on Docker

---

Intro

The deployment-configuration is based on docker compose. This repository conatains a set of compose-files that can be used to launch different environments of the MORE Platform using docker compose.

The repository contains several docker-compose.yaml files to allow a flexible configuration of the platform deployment. The basic deployment can be launched with the following command:

export DC_ENV=test
./docker-compose.sh up -d

About the docker-compose.sh script

The shell-script docker-compose.sh will combine different compose-files together:

• docker-compose.yaml - the basic defaults

• docker-compose.deploy.yaml - deployment overrides

  Adds additional services like watchtower and autohealer and configures the ingress for production

• docker-compose.${DC_ENV}.yaml - environment-specific overrides (optional)

  Allows adding environment-specific overrides

• docker-compose.local.yaml - local overrides (on the server, not managed by git)

  This allows to add additional overrides directly on the server.

This command launches all required components and configures the ingress proxy to enable ssl-termination with a letsencrypt certificate.

⚠️ Make sure to correctly set the email-address for the letsencrypt account and configure matching DNS-Names for the traefik-labels!
Those settings can be found in the docker-compose.deploy.yaml and should be configured in an env-specific or local override file - look for traefik.http.routers.*.rule.

The deployment also contains a watchtower-sidecar that keeps all container images at their latest version. It continuously checks the container-registries for new version and automatically updates the deployment whenever a new version is found.

Further, there's an autoheal service that continuously monitors the health-checks of all services and restarts any container that switches into the unhealthy state.

Environments

The minimal configuration for a new environment would contain the following settings:

services:
  ingress:
    environment:
      # let's-encrypt config
      TRAEFIK_CERTIFICATESRESOLVERS_LE_ACME_EMAIL: "more-platform@example.com"

  study-manager-backend:
    labels:
      'traefik.http.routers.studymanager-backend.rule': "Host(`studymanager.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/kibana`) || PathPrefix(`/oauth2`) || PathPrefix(`/login`))"
    environment:
      OAUTH2_SERVER: https://auth.example.com/realms/More-Platform
      OAUTH2_CLIENT_ID: study-manager
      OAUTH2_CLIENT_SECRET: ''
    
      MORE_FE_TITLE: "Example MORE Studymanager"
      MORE_FE_KC_SERVER: https://auth.example.com/
      MORE_FE_KC_REALM: More-Platform
      MORE_FE_KC_CLIENT_ID: study-manager

      LIME_URL: https://lime.example.com/admin/remotecontrol
      LIME_SURVEY_URL: https://lime.example.com/index.php
      LIME_END_SURVEY_URL: https://studymanager.example.com/api/v1/components/observation/lime-survey-observation/end.html
      LIME_ADMIN_PWD: "${LIME_ADMIN_PWD:-admin}"

  study-manager-frontend:
    labels:
      'traefik.http.routers.studymanager-frontend.rule': "Host(`studymanager.example.com`)"

  data-gateway:
    labels:
      'traefik.http.routers.dsb-gateway.rule': "Host(`data.example.com`)"

  limesurvey:
    labels:
      'traefik.http.routers.limesurvey.rule': "Host(`lime.example.com`)"

Remember to establish a suitable password for the LimeSurvey admin user (LIME_ADMIN_PWD). This password will be utilized to authenticate RESTful API calls from the backend to the LimeSurvey endpoint.

Tagging & Deployment Strategy

To ensure safe deployments, we use a tagging strategy for all MORE Platform components.

Tag Format

Git tags should follow the semantic versioning format: v<Major>.<Minor>.<Patch> (e.g., v1.0.1).

CI/CD Pipeline

GitHub Actions are configured to build and push images under the following conditions:

• Push to branches: main, develop
• Push tags: v*.*.*
• Pull Requests: Trigger builds to verify changes

Deployment

By default, the deployment uses the latest tag for images, which is automatically updated by watchtower when a new version is pushed to the registry on the supported branches. For production environments, it is recommended to pin specific versions in your environment-specific override files:

services:
  study-manager-backend:
    image: ghcr.io/more-platform/more-study-manager-backend:v1.0.1

Setup

Besides deploying the MORE Platform, some components and services require additional setup and configuration:

Auth Server

The Auth-Server is hosted externally and not as part of this deployment. See the Keycloak Setup Guide for further details and the required initial configuration.

Limesurvey Setup

Details of the required setup-procedure for limesurvey is covered in a separate documentation.