Programster's Blog

Tutorials focusing on Linux, programming, and open-source

Deploy Kimai Time Tracking With Docker

Kimai is a free, open-source tool that can be utilized for tracking your time and then possibly use that for the generation of invoices (I currently use Invoice Ninja for this). I found this tool as I needed to get a tool for collating my physical timesheets into an easily digestable format for generating my invoices from.



Create a docker-compose.yml file with the following contents:

version: "3.8"

    container_name: kimai
    image: kimai/kimai2:apache
    restart: always
      - "80:8001"
        - db
      - DATABASE_URL=mysql://kimai:${DATABASE_PASSWORD}@db:3306/kimai
      - TRUSTED_HOSTS=localhost,

    image: mysql:8
    container_name: db
    restart: always
      - mysql-data:/var/lib/mysql
      - MYSQL_DATABASE=kimai
      - MYSQL_USER=kimai

    driver: local

You need to change the value of to be your site's FQDN or server's IP address. If you are just running locally, then you can just take that line out.

Create Environment File

Now we need to create a very simple environment file that will contain a random password for our database, and give Docker a context name to use for prefixing things like volume names.

echo COMPOSE_PROJECT_NAME=kimai > .env
RANDOM_PASSWORD=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c24)


Now we can use Docker Compose to deploy Kimai by executing:

docker-compose up

You should see a bunch of text pass by, which should help indicate when it has finished starting up and configuring itself. You should be done when you see this message:

kimai  |  [OK] Kimai config was reloaded

In future, you can deploy with the services running in the background by executing the following instead.

docker-compose up -d

Create Super Admin User

Now we need to create our initial "super admin" user, which is basically a "god" user that has permission to do everything. We can do this by executing the following set of commands in a BASH shell (be sure to swap out the EMAIL and USERNAME variables with what you want).


docker exec -it kimai \
    /opt/kimai/bin/console kimai:create-user $USERNAME $EMAIL ROLE_SUPER_ADMIN

You should be prompted to enter a password, and once you do, you should get a success message as shown below:

Try It Out

Now that we have finished deployment, you should be able to use the tool by going to your server's IP or hostname in your browser. If you deployed locally, then one can just use http://localhost to access it.

You should be greeted with a screen like below:

Log in with the username and password you specified earlier when creating the super user and you should see the screen below:

You have now successfully deployed Kimai.


If you need to set up SSL/HTTPS then you need to look into using a reverse-proxy. You can do this with Docker through Jwilder's Docker image, or manually with Debian and Nginx.


Last updated: 24th December 2021
First published: 5th November 2021