Docker
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.
The Docker Hub repo, where you find the auto-building prod and dev containers for Kimai is: https://hub.docker.com/r/kimai/kimai2
Available tags
kimai/kimai2:apache
: the latest Kimai version bundled in an Apache container, needs a reverse proxy onlykimai/kimai2:fpm
: the latest Kimai version bundled in PHP-FPM Alpine container (smaller image, but needs extra setup steps)kimai/kimai2:latest
: same askimai/kimai2:fpm
kimai/kimai2:dev
: development image based on Apache, only to be used locally with debug mode and more
Each new release creates tag names containing the Kimai release number:
kimai/kimai2:apache-x.xx.x
: version specific release (Apache container)kimai/kimai2:fpm-x.xx.x
: version specific release (PHP-FPM container)
The following tags are deprecated and will not receive updates anymore, replace them:
kimai/kimai2:apache-prod
: replaced bykimai/kimai2:apache
kimai/kimai2:apache-latest
: replaced bykimai/kimai2:apache
kimai/kimai2:fpm-prod
: replaced bykimai/kimai2:fpm
kimai/kimai2:fpm-latest
: replaced bykimai/kimai2:fpm
kimai/kimai2:prod
: replaced bykimai/kimai2:fpm
kimai/kimai2:apache-dev
: replaced bykimai/kimai2:dev
kimai/kimai2:fpm-dev
: no replacementkimai/kimai2:apache-x.xx.x-dev
: no replacementkimai/kimai2:fpm-x.xx.x-dev
: no replacementkimai/kimai2:apache-x.xx.x-prod
: replaced bykimai/kimai2:apache-x.xx.x
kimai/kimai2:fpm-x.xx.x-prod
: replaced bykimai/kimai2:fpm-x.xx.x
Quick start
This will run the latest production build and make it accessible at http://localhost:8001.
This setup is NOT intended for production use as it is temporary and the data will disappear when the containers are removed (see point 4).
-
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
-
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 \ kimai/kimai2:apache
-
Add a user using the terminal
docker exec -ti kimai-test \ /opt/kimai/bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN
-
Stop the containers
docker stop kimai-mysql-testing kimai-test
-
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.
Updating Kimai
The usual update step is simple: stop, pull latest version, restart.
This example is based on the Apache
image used with the Docker compose
plugin:
# Pull latest version
docker compose pull
# Stop and remove older version
docker compose down
# Start the container
docker compose up -d
FPM image
The FPM image will need to be upgraded with a manual step.
Because the FPM image will have a HTTP proxy (e.g. caddy or nginx) serving the static assets the public
directory is mounted into that container. This is done via volumes:
version: '3.5'
services:
kimai:
image: kimai/kimai2:latest
...
volumes:
- public:/opt/kimai/public
...
nginx:
...
volumes:
- public:/opt/kimai/public:ro
...
When the kimai image is updated, and the container is restarted any new assets in the public directory are never included. These will be things like CSS files, images and especially version specific javascript code! To fix this you need to copy the newer files from a fresh image over the top.
# You might need to use `docker volume ls | grep kimai` to find the name of your Kimai "public" volume
docker run --rm -ti -v kimai_public:/public --entrypoint /bin/bash kimai/kimai2
# ^^^^^^^^^^^^ -> Kimai public volume
cp -r /opt/kimai/public /
exit
Now you’ll need to tell the running kimai to update its assets:
docker-compose exec kimai /opt/kimai/bin/console assets:install
That should do it.
Runtime Arguments
The following settings can set at runtime:
PHP memory limit
The maximum amount of memory a script may consume, https://php.net/memory-limit
memory_limit=512M
Kimai settings
See the Kimai and Symfony docs for more info on these.
DATABASE_URL=mysql://user:pass@hodt/dbname?charset=utf8mb4&serverVersion=8.3.0
APP_SECRET=change_this_to_something_unique
TRUSTED_PROXIES=nginx,localhost,127.0.0.1
TRUSTED_HOSTS=nginx,localhost,127.0.0.1
MAILER_FROM=kimai@example.com
MAILER_URL=null://localhost
Start up values:
If set, then these values will be used to create a new admin user (if not yet existing).
ADMINPASS=
ADMINMAIL=
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.
USER_ID=1000
GROUP_ID=1000
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 tokimai
DB_PASS
defaults tokimai
DB_HOST
defaults tosqldb
DB_PORT
defaults to3306
DB_BASE
defaults tokimai
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.