You can support us by downloading this article as PDF from the Link below. Download the guide as PDF

Kimai is a free, open source and online time-tracking software designed for small businesses and freelancers. It tracks work time and prints out a summary of your activities on demand. Yearly, monthly, daily, by customer, by project. The platform supports an unlimited amount of users and timesheet entries, so you can handle all of your teams or departments in one easy-to-use installation. And do not forget that Kimai is built with modern technologies such as Symfony, Bootstrap, RESTful API, Doctrine, AdminLTE, Webpack, ES6 and others.

Whether you are a freelancer, a small organization or a company with hundreds of employees, we shall setup Kimai and get to see the benefits that it will bring to you.

Features of Kimai Time Tracker

The following are some of the features you will immediately begin to enjoy from Kimai

  • Creation of invoices from your timesheets within your browser
  • Tracking of your working hours
  • An unlimited amount of users and timesheet entries
  • Tracking times using your mobile device
  • Translated into multiple languages and missing translations can be added easily, using the open translation standard Xliff.
  • Free and Open Source
  • Easy-to-use installation

Kimai’s Pre-requisites

Kimai’s simplicity on requires the following for it to run in your server

  • Web server (Apache or Nginx)
  • PHP
  • Composer
  • MySQL Database server

Once everything is set, let’s visit our Ubuntu 20.04 server and bid welcome this new Kimai visitor by following the following steps:

Step 1: Update and prepare your server

We are going to start on a clean slate and hence we shall update our server to get the latest software and patches. Apart from that, we shall install the tools we shall need in the next steps. Run the following commands to get our server updated and install necessary packages like git.

sudo apt update && sudo apt upgrade
sudo apt install git curl vim 

Step 2: Install and setup database

We are going to use MariaDB for this setup. Fortunately, we have a detailed guide already to get MariaDB 10.5 installed. Check out

How To Install MariaDB on Ubuntu

After you have the database installed, the next step is to create a database and user for Kimai. Let us, therefore, go ahead and get this done as shown below. You are free to name your database and user differently and ensure you use a safe password.

$ mysql -u root -p
Enter password: (Enter root Password>

MariaDB [(none)]> CREATE DATABASE kimai_database;
MariaDB [(none)]> CREATE USER 'userkimai'@'localhost' IDENTIFIED BY 'StrongPassword';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON kimai_database . * TO 'userkimai'@'localhost';
MariaDB [(none)]> exit;

Step 3: Install and configure a webserver and PHP

In order to get Kimai pages served, there has to be a webserver. Here, you have the freedom of either picking Apache or Nginx. We shall use Nginx for this guide. Additionally, Kimai requires PHP and therefore we will have to set it up as well. Note that the version of PHP required is PHP >=7.2.9. Therefore, we shall use PHP Version 7.4.

We have a complete guide that covers the installation of Nginx and PHP-FPM on Ubuntu. Kindly follow it then proceed below.

Open up your php-fpm ini file and add/edit the details shown below. They include Timezone, and memory limit settings. Add your date.timezone and change memory_limit to 512MB.

$ sudo vim /etc/php/7.4/fpm/php.ini

memory_limit = 512M

date.timezone = Africa/Nairobi

After that is done, install all required php extensions as follows

sudo apt install php-intl php-gd php-curl php-cli php-fpm php-json php-common php-mysql php-zip php-gd php-mbstring php-curl php-xml php-pear php-bcmath

Install composer

Composer is a brilliant tool that installs PHP dependencies that a project requires. We shall use its amazing features to install the dependencies that Flarum requires. Run the following commands to setup composer 1 that Kimai’s files are compatible with real quick.

cd ~
curl -sS -o composer-setup.php
sudo php composer-setup.php --version=1.10.17 --install-dir=/usr/local/bin --filename=composer

Step 4: Fetch Kimai’s files from Git and configure Nginx

We shall create a new directory (root) that Kimai’s files will reside as well as read and served by the webserver of our choice. You can create a different one according to your needs and design.

cd /var/www/html/
sudo git clone -b 1.11.1 --depth 1
cd kimai2/
sudo composer install --no-dev --optimize-autoloader

Configure the database connection in the .env file by setting the username, password and database we configured in Step 2.

$ sudo vim /var/www/html/kimai2/.env

##Edit the following
DATABASE_URL=mysql://userkimai:[email protected]:3306/kimai_database

And then run the Kimai installer:

cd /var/www/html/kimai2
sudo bin/console kimai:install -n

You should see something similar to the following during Kimai’s installation.

Then create your first user as follows. You will be prompted for a password, make sure it is more than 8 characters.

sudo bin/console kimai:create-user username [email protected] ROLE_SUPER_ADMIN

Generate Self-signed SSL/TLS certificates

Once Kimai installer is done, we will generate SSL/TLS certificates for Nginx SSL connection and create Nginx configuration file to define Kimai’s settings. This is just to make things a bit secure.

$ sudo mkdir /etc/ssl/private
$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/kimai-selfsigned.key -out /etc/ssl/certs/kimai-selfsigned.crt

##Enter Required details##
Generating a RSA private key
writing new private key to '/etc/ssl/private/kimai-selfsigned.key'
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:KE
State or Province Name (full name) [Some-State]:Nairobi
Locality Name (eg, city) []:Nairobi
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Computingforgeeks
Organizational Unit Name (eg, section) []:Infra
Common Name (e.g. server FQDN or YOUR name) []
Email Address []:[email protected]

Once it is done we will next generate Deffie-Hellman group as follows. It will take some time to complete.

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Then set the value of types_hash_max_size to 4096 in Nginx configuration file.

sudo sed -i 's/types_hash_max_size 2048/types_hash_max_size 4096/' /etc/nginx/nginx.conf

Configure Nginx

We now have to make a few changes to the Nginx configuration defaults by adding the details we need to serve Kimai. Change into sites-enabled, back up the default file and create a new one with new configurations.

$ cd /etc/nginx/sites-enabled/
$ sudo mv default /tmp

Create a new file and add the details shown below. If you have an FQDN, replace with it.

$ cd /etc/nginx/sites-enabled/
$ sudo vim kimai.conf
server {
    listen 80;
    return 301 https://$host$request_uri;
server {
    listen 443 ssl;

    root /var/www/html/kimai2/public/;
    index index.php index.htm index.nginx-debian.html;

        ssl_certificate /etc/ssl/certs/kimai-selfsigned.crt;
    ssl_certificate_key /etc/ssl/private/kimai-selfsigned.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on; 
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    ssl_ecdh_curve secp384r1;
    ssl_session_timeout  10m;
    ssl_session_cache shared:SSL:10m;
    resolver valid=300s;
    resolver_timeout 5s; 
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";

    location ~ /\.ht {
        deny all;
    location / {
                try_files $uri /index.php$is_args$args;

        location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_read_timeout 240;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_split_path_info ^(.+.php)(/.+)$;
    location ~ \.php$ {
        return 404;

Change Kimai’s files permissions

In order for Nginx to read Kimai’s files, we have to grant it the rights and the right permissions. Issue the commands below to get that done.

sudo chown -R www-data:www-data /var/www/html/kimai2/public/
sudo chmod -R 755 /var/www/html/kimai2/public/
sudo chmod -R g+rw /var/www/html/kimai2/var/
sudo chmod -R g+rw /var/www/html/kimai2/public/avatars/
sudo systemctl restart nginx php7.4-fpm

Once we are done, we should finally allow ports 80 and 443 on the firewall

sudo ufw allow 80,443/tcp

Step 5: Access Kimai Web Interface on Ubuntu 20.04

To complete setting up Kimai, point your browser to the IP or domain name of the webserver serving the files. https://[ip-or-domain-name]. You should be redirected to https and get a login page like below.

Enter the details we set in Step 4

Step 6: Multi-tenancy

Teams allow you to organize your users in groups and limit access to customers and projects. A team consists of a Teamlead and an unlimited amount of team members. The teamlead has access to all contents and timesheets of the team. Every content object can be linked to an arbitrary number of teams.

Permission details

With multi-tenancy in Kimai, we first have a look at the available user roles and how their permission work when using teams (this only applies when you use the default permission configuration):

  • System-Admin: can see and manage all content and use all administrative functions.
  • Administrator: can see and manage all content, but access to system specific settings and contents (like users) are limited.
  • Teamlead: can see all un-privileged contents and all contents assigned to his teams. Team specific contents can be managed for all teams where this user is the Teamlead.
  • User: can see all un-privileged contents and all contents assigned to his teams.

Creating users

Navigate to the “Users” Tab on the Kimai dashboard and click on it. After that, click on the + to create a new user.

Enter the details as shown below then click “Save” below the page

After saving it, a new page will be presented where you can add “Roles” and the rest. Enter the right roles for the user. Do this for as many users as you have.

Creating a team

Team creation is limited to the user roles System-Admin and Administrator. Navigate to the “Teams” Tab on the Kimai dashboard and click on it. Click on the + located at the top right to create a new team.

Enter the details of the team you are creating. You can add the members you would wish to be part of this team.

Later you can add Projects, Activites, Timesheets as well as plugins.


If you are serious about your projects, then it is prudent to have everything your team is handling on track. You need to know where every minute of productive time is being spend on and that will guarantee quality and timely products. Kimai is a good place to keep everything in sync and orderly. Give it a try and experience the benefits it proffers. Find out more about Kimai from its Official Website as well as its GitHub page. Finally, we appreciate your continued support and for spending time on the blog. You can enjoy other guides shared below.

Install Taiga Project Management Platform on Ubuntu

Setup Mautic Marketing Software on Ubuntu

Install and Configure OpenCart e-commerce platform on Ubuntu

You can support us by downloading this article as PDF from the Link below. Download the guide as PDF