How to Install and Use Kimai on Ubuntu (Complete Time-Tracking & Invoicing Guide)

Last Updated: July 11th, 2026

This comprehensive tutorial walks you through installing, configuring, securing, and using Kimai from scratch on an Ubuntu server. Kimai is a professional, open-source time-tracking application that lets you manage projects, record working hours, track expenses, and generate detailed invoices for clients—all within a clean, modern web interface.

What Is Kimai?

Kimai is a self-hosted time-tracking system designed for freelancers, small agencies, and enterprise teams. Proprietary SaaS time trackers charge hefty monthly per-user fees and store your proprietary billing data on external commercial servers. By self-hosting Kimai on your own Ubuntu infrastructure or VPS, you maintain total sovereignty over your financial logs, employee activity records, and client databases while enjoying infinite scalability and zero subscription costs.

Kimai Features

• Flexible Time Recording: Track time using a live stopwatch timer or manually input timespans and exact hour blocks.
• Multi-Level Hierarchy: Organize work efficiently using Customers, Projects, and specific Activities.
• Invoice & Report Generator: Export tracked data cleanly into customizable invoice layouts, PDF summaries, Excel sheets, or JSON streams.
• Advanced Rate Structures: Configure distinct hourly rates per user, per customer, per project, or per activity type, plus manage fixed fees and expenses.
• Roles & Permissions: Grant specific user roles ranging from basic team members and external contractors up to full administrators.

Requirements & Prerequisites

You will need an Ubuntu server (22.04, 24.04 LTS, or newer) with administrative sudo privileges, Docker and Docker Compose installed, a valid domain name, and an active TLS/SSL certificate (Let's Encrypt) to ensure your time-tracking portal remains secure and accessible over the internet.

Step 1: Install Docker and Docker Compose

Kimai runs cleanly and reliably inside containerized environments using an official image paired with a MySQL/MariaDB database backend. Log into your Ubuntu server and install Docker:

sudo apt update
sudo apt install -y docker.io docker-compose-v2
sudo systemctl start docker
sudo systemctl enable docker

Step 2: Create a Docker Compose Configuration for Kimai

Create a dedicated directory for your Kimai deployment and set up your multi-container compose configuration:

mkdir -p ~/kimai && cd ~/kimai
sudo nano docker-compose.yml

Paste the following production container stack configuration into the file:

services:
  sqldb:
    image: mariadb:10.11
    volumes:
      - mysql:/var/lib/mysql
    environment:
      - MYSQL_DATABASE=kimai
      - MYSQL_USER=kimaiuser
      - MYSQL_PASSWORD=SuperSecureDatabasePassword123
      - MYSQL_ROOT_PASSWORD=RootDatabasePassword456
    command: --default-storage-engine=innodb
    restart: unless-stopped

  kimai:
    image: kimai/kimai2:apache
    restart: always
    depends_on:
      - sqldb
    ports:
      - 127.0.0.1:8001:8001
    environment:
      - DATABASE_URL=mysql://kimaiuser:SuperSecureDatabasePassword123@sqldb:3306/kimai?charset=utf8mb4&serverVersion=10.11.2-MariaDB
      - TRUSTED_HOSTS=localhost,127.0.0.1,kimai.example.com
      - [email protected]
      - ADMINPASS=SuperSecureAdminPassword123!
    volumes:
      - kimai_data:/opt/kimai/var/data

volumes:
  mysql:
  kimai_data:

Save and close the file, then spin up your container stack in the background:

sudo docker compose up -d

Step 3: Configure an Nginx Reverse Proxy

Route public HTTP requests securely from your custom time-tracking domain (e.g., kimai.example.com) to the local container port 8001:

sudo apt install -y nginx
sudo nano /etc/nginx/conf.d/kimai.conf

Add the following server block configuration:

server {
    listen 80;
    server_name kimai.example.com;

    client_max_body_size 32M;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Test syntax and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Step 4: Secure with Let’s Encrypt HTTPS

Obtain an official SSL/TLS certificate via Certbot:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx --agree-tos --redirect --email [email protected] -d kimai.example.com

Step 5: Logging In and First-Time Usage Inside Kimai

Open your browser and navigate to your secure domain address: https://kimai.example.com. Log in using the default administrator credentials specified in your compose file (Email: [email protected], Password: SuperSecureAdminPassword123!—remember to update this password inside your profile settings immediately).

1. Step 1: Create a Customer: Navigate to the sidebar menu, click **Customers**, and select **+ Create Customer**. Input a client company name, choose your default currency (e.g., USD or EUR), and save.
2. Step 2: Create a Project: Go to **Projects**, click **+ Create Project**, and associate the project with the customer you just created.
3. Step 3: Define Activities: Go to **Activities**, click **+ Create Activity**, and define billable task descriptions (e.g., *Web Development*, *Consulting*, or *Design*).
4. Step 4: Tracking Time: Head over to the **Timesheet** view or use the green play icon at the top navigation bar to start a live timer instantly. Select your customer, project, and activity, add an optional description remark, and click **Record / Play**. When your task finishes, click the red stop button to save the entry precisely.
5. Step 5: Generating Invoices: Once you have accumulated recorded timesheet data for a client, click **Invoices**, pick a template layout, choose your date range and target customer, and click **Export** to generate a clean, professional invoice ready for client delivery.