Self-Host Kimai on a VPS: Open-Source Time Tracking

A time tracker holds sensitive data: who works for which customer, for how many hours, at what rate. On a SaaS platform that information lives with the vendor, and the bill grows with every seat you add. Hosting Kimai on your own VPS keeps the database within reach, lets you add users without licence fees, and puts you in charge of when upgrades happen.

Kimai is a PHP application built on the Symfony framework. Version 2 relies on MySQL or MariaDB; SQLite is no longer supported. The official kimai/kimai2 image comes in two flavours: apache (bundled web server, listening on port 8001) and fpm (meant to sit behind your own Nginx). The ServOrbit template uses kimai/kimai2:apache-latest with MySQL 8.0, so the whole stack is just two containers.

The ServOrbit Marketplace provisions the full stack on Ubuntu 24.04: Docker, MySQL 8.0, the Kimai container, the three volumes and a generated administrator password. You do not need a domain name to get started.

If you would rather install Kimai yourself on an existing VPS, here is a docker-compose.yml equivalent to the template, with one extra volume for plugins. Put it in a dedicated directory such as /opt/kimai.

services:
  db:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - kimai_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      retries: 12

  kimai:
    image: kimai/kimai2:apache-latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8001:8001"
    environment:
      DATABASE_URL: "mysql://kimai:${DB_PASSWORD}@db/kimai?charset=utf8mb4&serverVersion=8.0.34"
      APP_SECRET: ${APP_SECRET}
      ADMINMAIL: [email protected]
      ADMINPASS: ${ADMIN_PASSWORD}
      TRUSTED_HOSTS: "localhost,127.0.0.1,kimai.your-domain.com"
    volumes:
      - kimai_data:/opt/kimai/var/data
      - kimai_plugins:/opt/kimai/var/plugins
      - kimai_public:/opt/kimai/public/avatars

volumes:
  kimai_db:
  kimai_data:
  kimai_plugins:
  kimai_public:

Next, generate the secrets into a .env file, which Compose reads automatically, and start the stack. On first boot the container creates the database schema and the administrator account defined by ADMINMAIL and ADMINPASS.

cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
DB_ROOT_PASSWORD=$(openssl rand -hex 16)
APP_SECRET=$(openssl rand -hex 32)
ADMIN_PASSWORD=$(openssl rand -hex 12)
EOF
chmod 600 .env
docker compose up -d
docker compose logs -f kimai

The web UI is enough for daily account management, but the Kimai Symfony console is invaluable for scripted onboarding or for regaining access. The kimai:user:create command takes a username, an email address and a role, then prompts for the password:

docker compose exec kimai /opt/kimai/bin/console kimai:user:create alice [email protected] ROLE_TEAMLEAD

The same console offers kimai:reload to rebuild the cache after a configuration change, and kimai:update to run database migrations on installations outside Docker. Run bin/console list kimai inside the container to see the commands available in your version.

Kimai organises time on three levels. A customer carries the currency, the time zone and the billing details. A project belongs to a customer and can have start and end dates, an order number and a budget. An activity describes the kind of work (development, meeting, support); it can be attached to a single project or be global, available everywhere. Each timesheet entry ties together a user, a project, an activity, a time range and, if needed, a description and tags. Getting this hierarchy right from the start saves painful clean-ups later: one customer per billed entity, one project per engagement or contract, and global activities for cross-cutting work.

Kimai uses hierarchical roles, and the Roles and permissions screen lets you fine-tune what each role can see and change. Teams complete the picture: a customer, project or activity restricted to a team is only visible to its members, and the team lead can review and adjust the hours of their team without seeing the rest of the company. For an outside contractor, create a user account limited to a dedicated team.

The invoicing module turns a selection of hours into a document. From the Invoices menu you pick a customer, a period, optionally a project, and then a template. Kimai computes the amounts from the rates, shows a preview and stores the invoice with a status (pending, paid, cancelled). Billed entries can be marked as exported, which prevents double billing and protects them from later edits.

Kimai exposes a REST API covering customers, projects, activities, timesheets and users. Its interactive documentation is served by your own instance at /api/doc, always in sync with the installed version. To authenticate a script, create an API token from your user profile and send it as a header:

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  https://kimai.your-domain.com/api/timesheets

A token inherits its user's permissions, so create a service account with the minimum role required instead of using the super-admin. The API lets you start a timer from a shortcut, feed hours into a dashboard, or sync projects with your ticketing tool.

Kimai has a plugin store on its official website, with free and paid extensions: expenses, custom fields, timesheet approval workflows, imports from other tools. A plugin is a directory placed in var/plugins/. With Docker, mount that directory on a volume, or it disappears whenever the container is recreated — that is what kimai_plugins does in the compose file above. A typical installation:

docker compose cp PluginNameBundle kimai:/opt/kimai/var/plugins/
docker compose exec kimai /opt/kimai/bin/console kimai:reload --env=prod

Some plugins add database tables and ship their own install command; follow the plugin page and check compatibility with your Kimai version before every upgrade.

Almost everything lives in the MySQL database; the kimai_data and kimai_public volumes complete the backup. A logical dump is more portable than a hot copy of the MySQL files:

docker compose exec -T db sh -c 'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > kimai-$(date +%F).sql
docker run --rm -v kimai_kimai_data:/data -v "$PWD":/backup alpine tar czf /backup/kimai_data-$(date +%F).tgz -C /data .

The actual volume name is prefixed with the Compose project name, so check it with docker volume ls. To restore, start an empty stack with the same .env, then load the dump back:

docker compose exec -T db sh -c 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < kimai-YYYY-MM-DD.sql

Schedule the dump nightly with cron, copy it off the VPS (Restic, BorgBackup or object storage) and test a restore at least once: a backup that has never been restored is only a hypothesis.

Most Kimai-on-Docker incidents come down to a handful of known causes. Always start with docker compose logs kimai and docker compose ps.

Kimai is frugal: most of the load comes from MySQL and from reports over long periods. For a freelancer or a small team, 1 vCPU and 1 to 2 GB of RAM is enough. Beyond roughly twenty active users, or if you regularly produce yearly reports and large exports, plan for 2 vCPUs and 4 GB, which leaves headroom for the MySQL InnoDB cache. Disk usage stays modest: a few gigabytes cover years of timesheets, but keep room for local dumps before they are shipped off the server.