Running Kimai inside docker

We offer Kimai Docker images, both for development and a docker-compose setup suitable for running in a production environment.

Any issues with the container rather than the application itself can be raised here.

Docker Hub

The Docker Hub repo, where you find the auto-building prod and dev containers for Kimai is:

Quick start

This will run the latest production build and make it accessible at http://localhost:8001.

  1. Start a DB

     docker run --rm --name kimai-mysql-testing \
         -e MYSQL_DATABASE=kimai \
         -e MYSQL_USER=kimai \
         -e MYSQL_PASSWORD=kimai \
         -e MYSQL_ROOT_PASSWORD=kimai \
         -p 3399:3306 -d mysql
  2. Start Kimai

     docker run --rm --name kimai-test \
         -ti \
         -p 8001:8001 \
         -e DATABASE_URL=mysql://kimai:kimai@${HOSTNAME}:3399/kimai?charset=utf8mb4&serverVersion=8.3.0 \
  3. Add a user using the terminal

     docker exec -ti kimai-test \
         /opt/kimai/bin/console kimai:user:create admin ROLE_SUPER_ADMIN
  4. Stop the containers

     docker stop kimai-mysql-testing kimai-test
  5. When you are finished testing Kimai, you can remove the containers (warning: you will lose your data!).

     docker rm kimai-mysql-testing kimai-test

If you are happy with Kimai, you can now setup your Docker installation using Docker Compose.

Runtime Arguments

The following settings can set at runtime:

PHP memory limit

The maximum amount of memory a script may consume,


Kimai core settings

See the Kimai and Symfony docs for more info on these.


Start up values:

If set, then these values will be used to create a new admin user (if not yet existing).


Changing UID and GID

It is possible to set the user that FPM or Apache run as. If the user does not exist a new user called www-kimai is created and the server is then run under that user. Note these must be numbers, not names.


Alternate DB config

It is possible to pass the DB config in individual values. If the ENV variable DB_TYPE is set then the following values will be expected:

The DB_TYPE must be mysql:

  • DB_USER defaults to kimai
  • DB_PASS defaults to kimai
  • DB_HOST defaults to sqldb
  • DB_PORT defaults to 3306
  • DB_BASE defaults to kimai

The official docker documentation has more options on running the container.

Tips & Tricks

If you’re using Docker for Windows or Docker for Mac, and you’re getting “Connection refused” or other errors, you might need to change ${HOSTNAME} to host.docker.internal. This is because the Kimai Docker container can only communicate within its network boundaries. Alternatively, you can start the container with the flag --network="host". See here for more information.