2.3. Docker Installation¶

eduMFA can be easily deployed using Docker containers. This guide will walk you through the process of installing eduMFA using Docker images from GitHub Registry.

2.3.1. Prerequisites¶

Before proceeding, ensure that you have:

Docker installed on your system
Access to GitHub Registry

2.3.2. Docker Compose¶

For the most setups you should use Docker Compose. Here’s a sample docker-compose.yml file also containing a mariadb service.

The container contains a default logging configuration printing the logs to stdout, performs database maintenance on start and runs the application on port 8000.

services:
  mariadb:
    image: docker.io/mariadb:lts-noble
    restart: always
    volumes:
      - mariadb-data:/var/lib/mysql:rw
    environment:
      MARIADB_DATABASE: ${MARIADB_DATABASE}
      MARIADB_USER: ${MARIADB_USER}
      MARIADB_PASSWORD: ${MARIADB_PASSWORD}
      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3

  edumfa:
    image: ghcr.io/edumfa/edumfa:latest
    restart: always
    ports:
      - "8000:8000"
    volumes:
      - edumfa-keys:/etc/edumfa/:rw
    environment:
      DB_DRIVER: mysql+pymysql
      DB_HOSTNAME: mariadb
      DB_USER: ${MARIADB_USER}
      DB_PASSWORD: ${MARIADB_PASSWORD}
      DB_DATABASE: ${MARIADB_DATABASE}
      SECRET_KEY: ${EDUMFA_SECRET_KEY}
      EDUMFA_PEPPER: ${EDUMFA_PEPPER}
      EDUMFA_ADMIN_USER: ${EDUMFA_ADMIN_USER}
      EDUMFA_ADMIN_PASS: ${EDUMFA_ADMIN_PASS}
      EDUMFA_UI_DEACTIVATED: ${EDUMFA_UI_DEACTIVATED}
    depends_on:
      mariadb:
        condition: service_healthy

volumes:
  edumfa-keys:
  mariadb-data:

The .env file should contain the following variables:

MARIADB_USER: the MariaDB user
MARIADB_PASSWORD: the MariaDB password
MARIADB_DATABASE: the MariaDB database
MARIADB_ROOT_PASSWORD: the MariaDB root password (not used by eduMFA, required)
EDUMFA_SECRET_KEY: the secret key which signs API tokens, should be at least 24 random characters long
EDUMFA_PEPPER: the pepper to use for password hashing, should be at least 24 random characters long
EDUMFA_ADMIN_USER: the username for the local eduMFA admin (optional)
EDUMFA_ADMIN_PASS: the password for the local eduMFA admin (optional)
EDUMFA_LOGCONFIG: a path to an alternative logging config (optional)
SUPERUSER_REALM: which realms should be superuser realms (optional)
EDUMFA_UI_DEACTIVATED: whether to disable the WebUI (optional)
EDUMFA_LOGO: filename of custom logo (optional)
EDUMFA_PAGE_TITLE: custom page title (optional)
EDUMFA_CSS: url of custom css stylesheet (optional)

You can also add a “_FILE” suffix to each variable name and pass a path to read the value from a file instead. For example instead of passing SECRET_KEY:

SECRET_KEY_FILE: /etc/edumfa/secret_key.txt

Alternatively, you can mount your own edumfa.cfg instead of configuring eduMFA via environment variables.

To start eduMFA using Docker Compose, run:

docker compose up -d

For more information on using eduMFA, please refer to First Steps.

2.3.3. Pulling the eduMFA Docker Image¶

To pull the eduMFA Docker image without docker compose from GitHub Registry, use the following command:

docker pull ghcr.io/edumfa/edumfa:latest

You can replace latest with a specific version tag if needed e.g. 2.2.0

2.3.4. Running eduMFA Container¶

To run the eduMFA container, use the following command:

docker run -d -p 8000:8000 --name edumfa ghcr.io/edumfa/edumfa:latest

This command will:

Run the container in detached mode (-d)
Map port 8000 on the host to port 8000 in the container (-p 8000:8000)
Name the container “edumfa” (–name edumfa)

2.3.5. Running your own scripts¶

To run your own scripts on startup, put it into the /opt/edumfa/user-scripts/ directory with a .sh suffix:

docker run -d -p 8000:8000 -v /path/to/script.sh:/opt/edumfa/user-scripts/script.sh --name edumfa ghcr.io/edumfa/edumfa:latest

It will be executed as a bash script. It’s also possible to execute multiple files by placing multiple scripts with the suffix there [1].

2.3.6. Persistent Data¶

To persist data between container restarts, you can mount a volume for the database:

docker run -d -p 8000:8000 -v /path/to/edumfa.cfg:/etc/edumfa/edumfa.cfg -v edumfa-config:/etc/edumfa --name edumfa ghcr.io/edumfa/edumfa:latest

This will create a named volume edumfa-config that will persist your eduMFA configuration. This volume will contain the encryption key and the audit key.

Depending on your own configuration and your individual setup you may need to adjust the paths.

2.3.7. Updating eduMFA manually¶

To update eduMFA to a newer version, pull the latest image and recreate the container:

docker pull ghcr.io/edumfa/edumfa:latest
docker stop edumfa
docker rm edumfa
docker run -d -p 8000:8000 -v /path/to/edumfa.cfg:/etc/edumfa/edumfa.cfg -v edumfa-config:/etc/edumfa --name edumfa ghcr.io/edumfa/edumfa:latest

Footnotes