Running Multiple Independent Kimai Instances with Docker

This guide explains how to run multiple productive Kimai instances using Docker. In this example, files are created in /opt/kimai-mydomain. The folder name is not critical, but using descriptive names helps distinguish different instances.

---

Step 1: Create docker-compose.yml

Create /opt/kimai-mydomain/docker-compose.yml:

services:
  mariadb:
    image: mariadb:latest
    environment:
      - MYSQL_DATABASE=kimai
      - MYSQL_USER=kimai
      - MYSQL_PASSWORD=${MARIADB_PASSWORD}
      - MYSQL_ROOT_PASSWORD=${MARIADB_ROOT_PASSWORD}
    volumes:
      - ./mariadb_data:/var/lib/mysql
    command: --default-storage-engine innodb
    restart: unless-stopped
    healthcheck:
      test: mysqladmin -p${MARIADB_ROOT_PASSWORD} ping -h localhost
      interval: 20s
      start_period: 10s
      timeout: 10s
      retries: 3

  kimai:
    image: kimai/kimai2:apache-debian-master-prod
    environment:
      - APP_ENV=prod
      - TRUSTED_HOSTS=localhost,${HOSTNAME}
      - [email protected]
      - ADMINPASS=${KIMAI_ADMIN_PASSWORD}
      - DATABASE_URL=mysql://kimai:${MARIADB_PASSWORD}@mariadb/kimai
    volumes:
      - ./kimai_var:/opt/kimai/var
    ports:
      - '17919:8001'
    depends_on:
      - mariadb
    restart: unless-stopped

Note: No changes are needed in this file. All relevant configuration is loaded from .env.

---

Step 2: Create .env

Create /opt/kimai-mydomain/.env:

MARIADB_ROOT_PASSWORD=eishi5Pae3chai1Aeth2wiuCh7Ahhi
MARIADB_PASSWORD=su1aesheereithubo0iedootaeRooT
KIMAI_ADMIN_PASSWORD=toiWaeShaiz5Yeifohngu6chunuo6C
KIMAI_ADMIN_EMAIL=[email protected]
HOSTNAME=kimai.mydomain.com

• Generate random passwords for .env. 🚫 Do not use the defaults above.
• Set KIMAI_ADMIN_EMAIL and HOSTNAME correctly.

---

Step 3: Create Data Directory and Set Permissions

mkdir -p kimai_var
chown -R 33:33 kimai_var

(33:33 corresponds to the www-data user inside the container.)

---

Step 4: Initial Installation

Recent versions of Kimai will automatically install into the database on first startup.

To see the password of the automatically created admin user:

docker-compose logs | grep -i ROLE_SUPER_ADMIN

Once you see a line like:

[Sun Mar 07 23:53:35.986477 2021] [core:notice] [pid 50] AH00094: Command line: '/usr/sbin/apache2 -D FOREGROUND'

stop the process using Ctrl+C — this means Kimai has finished installing.

---

Step 5: Create a Systemd Service

Use TechOverflow’s script to create a systemd service for your project:

curl -fsSL https://techoverflow.net/scripts/create-docker-compose-service.sh | sudo bash /dev/stdin

---

Step 6: Configure Nginx Reverse Proxy

Create an Nginx config for your Kimai domain. Example:

server {
    server_name  kimai.mydomain.com;

    location / {
        proxy_pass http://localhost:17919/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_redirect default;
    }

    listen [::]:443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/kimai.mydomain.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/kimai.mydomain.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
}

server {
    if ($host = kimai.mydomain.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    server_name  kimai.mydomain.com;

    listen [::]:80; # managed by Certbot
    return 404; # managed by Certbot
}

---

Step 7: Access Kimai

After configuration, open your browser and visit:

https://kimai.mydomain.com

Login using the credentials from .env:

• Email: KIMAI_ADMIN_EMAIL
• Password: KIMAI_ADMIN_PASSWORD

---

✅ Notes

• Always use TLS with Let’s Encrypt, even for test setups.

---

Credit https://techoverflow.net/2021/03/08/a-modern-kimai-setup-using-docker-compose-and-nginx/