Kimai on VPS: installation, configuration, and maintenance

Installing Kimai on a VPS involves deploying Docker containers with the application and database, configuring a reverse proxy for domain access with HTTPS support, and planning regular backups and updates to ensure stable self-hosted operation. This allows you to get a full-fledged time-tracking system, completely controlled by you.

Kimai is a powerful and flexible open-source web application designed for time tracking, project tracking, and client management. It is ideal for freelancers, small and medium-sized companies, and teams that require detailed control over time spent and invoicing. By deploying Kimai on your own VPS, you gain full control over data, security, and performance, avoiding the limitations and subscription fees of cloud services. In this article, we will detail how to perform a Kimai installation on your virtual server, using Docker for maximum simplicity and portability.

What is Kimai and why do you need it on a VPS?

Kimai is a modern cross-platform time-tracking solution that helps effectively manage working hours. It allows you to record hours spent on various projects and tasks, generate reports, issue invoices, and much more. The main advantage of Kimai is its flexibility and the ability to be Kimai self-hosted on your own server, which ensures independence from third-party providers and full sovereignty over your data.

Key features and benefits of Kimai

• Flexible time tracking: Record time manually or use the built-in stopwatch. Ability to link time to clients, projects, and tasks.
• Client and project management: Create and manage an unlimited number of clients and projects, assign rates for each.
• Detailed reports: Generate customizable reports on time, expenses, profit, export them in various formats (CSV, PDF, XLSX).
• Invoicing: Integrated functions for creating invoices based on tracked time.
• Multi-user support: Add users with different roles and permissions (administrator, manager, user).
• Open source: Full transparency and the ability to customize to your needs.
• API: RESTful API for integration with other systems.
• Plugins and extensions: Extensive possibilities for expanding functionality.

Why a VPS for Kimai?

The choice of VPS hosting for Kimai on a server is due to several important factors. A virtual private server provides an ideal balance between cost, performance, and control. Unlike regular shared hosting, a VPS gives you root access, allowing you to install any necessary software (e.g., Docker), configure system parameters, and ensure security at the required level. This is critically important for deploying applications like Kimai, which require a specific server environment.

Hosting Kimai VPS also ensures that your data will be stored in your chosen data center, complying with local or corporate privacy requirements. You are free from the risks associated with the data usage policies of third-party services and can be confident in their security. Additionally, you get predictable performance that is not dependent on "neighbors" on the server, which is often a problem with shared hosting. This is especially important for scaling, as the number of users and data in Kimai grows.

Kimai System Requirements: What You Need to Know?

Before proceeding with the Kimai installation, it is important to understand what resources your virtual server will require. Kimai is relatively undemanding in terms of resources for small teams, but as the number of users and data volume grows, the requirements increase. Using Docker simplifies dependency management but does not negate the need for sufficient CPU, RAM, and disk space.

Minimum and Recommended Configurations for Kimai Self-Hosted

Kimai runs on PHP (version 8.1 or higher) and requires a database (MySQL 8.0+, MariaDB 10.5+, or PostgreSQL 13+). To work with Docker, you will also need enough space for images and containers.

• Minimum requirements (up to 5 users, small number of projects):
  • CPU: 1 vCore
  • RAM: 1 GB (minimum 512 MB for Kimai + 512 MB for OS and Docker)
  • Disk: 20 GB NVMe (for OS, Docker images, and data)
  • Operating System: Ubuntu 22.04+, Debian 11+
• Recommended requirements (up to 20 users, active use, reports):
  • CPU: 2 vCores
  • RAM: 2 GB
  • Disk: 40 GB NVMe
  • Operating System: Ubuntu 22.04+, Debian 11+
• For large teams (20+ users, intensive work, API integrations):
  • CPU: 4+ vCores
  • RAM: 4+ GB
  • Disk: 80+ GB NVMe
  • Operating System: Ubuntu 22.04+, Debian 11+

It is important to remember that NVMe drives significantly speed up the database and application as a whole, making them preferable for Kimai self-hosted.

Choosing an Operating System

For deploying Kimai on a VPS via Docker, the most optimal choice are Linux distributions such as Ubuntu Server (22.04 LTS and higher) or Debian (11 and higher). These OS are well-documented, have broad community support, and work stably with Docker. Ubuntu is often chosen for its ease of use and up-to-date packages, Debian for its stability and minimalism. In this article, all commands will be presented for Debian/Ubuntu-based systems.

Preparing the VPS for Kimai Docker Installation

Before proceeding with the actual Kimai installation, you need to prepare your virtual server. This includes updating the system, installing Docker and Docker Compose, and configuring a domain name.

System Update and Docker/Docker Compose Installation

Connect to your VPS via SSH. First, update the system packages to ensure you have the latest software versions and security patches:

sudo apt update && sudo apt upgrade -y

Next, install Docker. It is recommended to use the official Docker repository to get the most up-to-date version. Execute the following commands:

# Install necessary packages
sudo apt install ca-certificates curl gnupg lsb-release -y

# Add Docker's GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update package index and install Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Check that Docker is installed and running:

sudo systemctl status docker

You should see "active (running)" status. Add your user to the docker group so you don't have to use sudo for every Docker command:

sudo usermod -aG docker $USER
newgrp docker

Now you can verify the Docker installation by running:

docker run hello-world

And ensure the Docker Compose plugin is working:

docker compose version

Domain Name and DNS Configuration

To access Kimai on the server via a browser using a friendly name instead of an IP address, you will need a domain name. Register a domain with any registrar and configure an A-record pointing to your VPS's IP address. For example, if your domain is yourdomain.com, you can create a subdomain kimai.yourdomain.com and point it to your server's IP. Make sure the DNS records have updated (this can take up to several hours).

Step-by-step Kimai Installation on VPS with Docker Compose

Now that your VPS is ready, you can proceed with the Kimai Docker installation. We will use Docker Compose to define and run all necessary services (Kimai, database).

Creating the docker-compose.yml file

Create a directory for your Kimai files and navigate into it:

mkdir -p ~/kimai
cd ~/kimai

Create a docker-compose.yml file using a text editor (e.g., nano):

nano docker-compose.yml

Paste the following content. This is a standard configuration for Kimai self-hosted using MySQL/MariaDB. Replace YOUR_DOMAIN.COM, YOUR_DB_PASSWORD, YOUR_DB_USER, YOUR_DB_NAME with your own values.

version: '3.8'

services:
  database:
    image: mariadb:10.11
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - database_data:/var/lib/mysql
    networks:
      - kimai-network

  kimai:
    image: kimai/kimai2:latest
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      - database
    ports:
      - "8001:8000" # Kimai by default listens on port 8000 inside the container
    networks:
      - kimai-network

volumes:
  database_data:

networks:
  kimai-network:
    driver: bridge

Now create an .env file in the same directory. This file will contain environment variables for the database and Kimai. Replace YOUR_DB_PASSWORD, YOUR_DB_USER, YOUR_DB_NAME with your own values. Make sure the password is strong enough.

nano .env

# Database configuration
DATABASE_URL=mysql://YOUR_DB_USER:YOUR_DB_PASSWORD@database:3306/YOUR_DB_NAME?serverVersion=10.11&charset=utf8mb4

# Kimai configuration
APP_ENV=prod
APP_SECRET=your_secret_key_here # Generate a unique key, e.g., "openssl rand -base64 32"
TRUSTED_HOSTS=^localhost$,^127\.0\.0\.1$,^YOUR_DOMAIN\.COM$ # Replace with your domain
MAILER_URL=smtp://user:[email protected]:587 # Optional: for Kimai email sending

For APP_SECRET, generate a unique key, for example, with the command openssl rand -base64 32. TRUSTED_HOSTS should include your domain through which you will access Kimai. For example, if you use kimai.yourdomain.com, the string will be TRUSTED_HOSTS=^localhost$,^127\.0\.0\.1$,^kimai\.yourdomain\.com$. If you use multiple domains or subdomains, separate them with commas.

Starting Kimai and Initial Setup

After creating the docker-compose.yml and .env files, you can start Kimai:

docker compose up -d

The -d option runs the containers in the background. Docker will download the necessary images (MariaDB and Kimai), create the containers, and start them. This may take a few minutes on the first run.

Check the status of the running containers:

docker compose ps

You should see both containers (kimai-database-1 and kimai-kimai-1) in "running" status.

Now Kimai is accessible via your VPS's IP address and port 8001 (e.g., http://YOUR_IP_ADDRESS:8001). Open this address in your browser. You should see the Kimai login page.

Standard administrator credentials for the first login:

• Username: admin
• Password: kimai

Be sure to change these credentials immediately after the first login!

At this point, the Kimai installation is complete. However, for secure and convenient access via a domain name with HTTPS, you will need to configure a reverse proxy.

Configuring Reverse Proxy and HTTPS for Kimai on the Server

Direct access to Kimai via an IP address and a non-standard port (8001) is not an ideal solution. For a professional deployment of Kimai on the server, it is recommended to use a reverse proxy (e.g., Nginx or Caddy) to route traffic to the Kimai container and provide HTTPS encryption using Let's Encrypt.

Using Nginx as a Reverse Proxy

Nginx is a high-performance web server that is excellent for the role of a reverse proxy. If Nginx is not yet installed on your VPS, install it:

sudo apt install nginx -y

Create a new configuration file for your Kimai domain:

sudo nano /etc/nginx/sites-available/kimai.conf

Paste the following configuration, replacing kimai.yourdomain.com with your actual domain:

server {
    listen 80;
    listen [::]:80;
    server_name kimai.yourdomain.com;

    # Redirect HTTP to HTTPS (will be configured by Certbot later)
    # return 301 https://$host$request_uri;

    location / {
        proxy_pass http://localhost:8001; # Port on which Kimai listens inside the container
        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;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_http_version 1.1;
        proxy_read_timeout 900s;
        proxy_send_timeout 900s;
        proxy_connect_timeout 900s;
        proxy_redirect off;
    }
}

Save the file and create a symbolic link to it in sites-enabled:

sudo ln -s /etc/nginx/sites-available/kimai.conf /etc/nginx/sites-enabled/

Check the Nginx configuration for errors and restart it:

sudo nginx -t
sudo systemctl restart nginx

Now you can access Kimai via your domain name (e.g., http://kimai.yourdomain.com). The next step is to enable HTTPS.

Automating HTTPS with Let's Encrypt via Certbot

Let's Encrypt provides free SSL/TLS certificates, and Certbot automates the process of obtaining and installing them. Install Certbot and the Nginx plugin:

sudo apt install certbot python3-certbot-nginx -y

Run Certbot for your domain. It will automatically find the Nginx configuration and set up HTTPS:

sudo certbot --nginx -d kimai.yourdomain.com

Certbot will ask a few questions (email, agreement to terms). After successful execution, it will automatically update the Nginx configuration, adding HTTPS and redirecting from HTTP to HTTPS. Check that automatic certificate renewal is working:

sudo systemctl status certbot.timer

Now your Kimai VPS is accessible via a secure HTTPS connection (https://kimai.yourdomain.com).

Alternative: Caddy for Simplicity

For those looking for a simpler solution for reverse proxy and HTTPS, Caddy is an excellent choice. Caddy automatically obtains and renews Let's Encrypt certificates for all configured domains "out of the box".

Install Caddy (instructions may vary slightly depending on the OS, but for Debian/Ubuntu it's usually like this):

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

Create a Caddyfile configuration file:

sudo nano /etc/caddy/Caddyfile

Replace the content with the following, specifying your domain:

kimai.yourdomain.com {
    reverse_proxy localhost:8001
}

Restart Caddy:

sudo systemctl restart caddy

Caddy will automatically configure HTTPS for your domain. This is significantly simpler than manual Nginx and Certbot setup, but Nginx offers more options for fine-tuning.

Maintaining Kimai on VPS: Backups and Updates

Maintaining a Kimai self-hosted instance requires regular maintenance, including data backup and timely updates. These steps are critical to ensuring the stability, security, and availability of your application.

Backup Strategies for Kimai Self-Hosted

Backup is the most important aspect of any server maintenance. For Kimai, you need to regularly back up two main components:

1. Database: Contains all time entries, clients, projects, users, and settings.
2. Kimai Data: Includes configuration files, uploaded files (if Kimai uses them), and other application-specific data. In our case, since Kimai is running in Docker, the main changeable files are those stored in volumes.

For a MariaDB/MySQL database running in Docker, you can use the mysqldump command from inside the container:

# Get the database container name
DB_CONTAINER_NAME=$(docker compose ps -q database)

# Perform database backup
docker exec $DB_CONTAINER_NAME sh -c 'exec mysqldump -u YOUR_DB_USER -pYOUR_DB_PASSWORD YOUR_DB_NAME' > ~/kimai_backup/kimai_db_$(date +%F).sql

Replace YOUR_DB_USER, YOUR_DB_PASSWORD, YOUR_DB_NAME with the actual values from your .env file.

To back up Docker volumes where Kimai data is stored (if you mounted additional volumes for files, besides the database):

# Create an archive of the Kimai data directory if it contains important files
# For example, if you use a local volume for settings or uploaded files
tar -czvf ~/kimai_backup/kimai_files_$(date +%F).tar.gz ~/kimai/

It is recommended to automate this process using Cron jobs. For example, for a daily database backup:

crontab -e

Add the line (replace the script path and credentials):

0 3 * * * /bin/bash -c "DB_CONTAINER_NAME=$(docker compose ps -q database) && docker exec $DB_CONTAINER_NAME sh -c 'exec mysqldump -u YOUR_DB_USER -pYOUR_DB_PASSWORD YOUR_DB_NAME' > /path/to/your/kimai_backup/kimai_db_$(date +\%F).sql"

For a more comprehensive approach to VPS backup, including incremental backups and storage on remote repositories, consider tools like Restic. This will ensure reliable storage and quick recovery in case of failures.

Kimai Docker Update Process

Updating Kimai deployed via Docker Compose is a relatively simple process. Regular updates are important for new features, bug fixes, and security patches.

Before updating, always back up your database!

# Navigate to the directory with docker-compose.yml
cd ~/kimai

# Stop current containers
docker compose down

# Remove old images (optional, but recommended for cleanliness)
docker compose rm -f

# Download new images and start containers
docker compose pull
docker compose up -d

After starting the new containers, Kimai will automatically perform necessary database migrations on the first run of the new image. If you encounter problems after updating, check the Kimai container logs:

docker compose logs kimai

If Kimai requires any additional commands for database migration or cache clearing after an update, this is usually indicated in the official Kimai documentation. For example, sometimes it is necessary to run:

docker compose exec kimai bin/console doctrine:migrations:migrate --no-interaction
docker compose exec kimai bin/console cache:clear

However, for most minor updates, a simple docker compose pull && docker compose up -d is sufficient.

Choosing a VPS Configuration for Kimai: Real Scenarios

Choosing the right Kimai VPS configuration directly impacts performance and cost. For Kimai self-hosted, it's important to find a balance between sufficient resources for comfortable operation and reasonable costs. Valebyte offers various tariff plans that can suit Kimai for different load scenarios.

VPS Comparison Table for Kimai under Different Loads

Below is a table with recommendations for VPS configurations for Kimai, based on the number of users and intensity of use. Prices are approximate and may vary.

Usage Scenario	Users	vCPU	RAM	Disk (NVMe)	Example Valebyte Plan*	Approximate Price/Month*
Personal / Testing	1-3	1	1 GB	20 GB	VPS-1 Core	$5 - $7
Small Team / Freelance	4-10	2	2 GB	40 GB	VPS-2 Core	$10 - $15
Medium Team / Active Use	11-25	2-4	4 GB	80 GB	VPS-4 Core	$20 - $30
Large Team / Corporate	25+	4-8	8+ GB	160+ GB	VPS-8 Core	$40+

*Prices and plan names are examples and may differ from Valebyte's current offering. Always check current tariffs on the provider's website.

It is important to remember that NVMe drives significantly increase database speed, which is critical for Kimai's performance, especially when generating reports and handling a large number of entries.

Scaling Recommendations

As your team and data volume in Kimai grow, you may need to scale your VPS. Here are some tips:

1. Resource Monitoring: Regularly monitor CPU load, RAM usage, and disk space on your VPS. Tools like htop, glances, or Prometheus/Grafana will help you understand which resources are bottlenecks.
2. RAM Scaling: Most often, RAM becomes the first bottleneck, especially for the database. Increasing RAM usually provides a noticeable performance boost.
3. CPU Scaling: If users frequently experience delays when performing complex queries or generating reports, increasing the number of CPU cores can help.
4. Database Optimization: Ensure your database is optimally configured. For MariaDB/MySQL, this may include setting innodb_buffer_pool_size and other parameters in my.cnf.
5. Choosing a More Powerful VPS: If the current VPS is not coping, consider upgrading to a more powerful plan. The flexibility of VPS hosting allows for easy resource upgrades without reinstallation. Many other productivity applications, such as Kanboard or Invoice Ninja, may also require a similar approach to resource scaling.
6. Cleaning Old Data: If Kimai has been used for a long time and you no longer need old data, consider archiving or deleting it to maintain database performance.

Conclusion

Installing and configuring Kimai on a VPS via Docker Compose is an effective way to get a powerful time-tracking system with full control over your data. It is important not only to deploy the application correctly but also to ensure its security, regular backups, and timely updates. By choosing a VPS from Valebyte with NVMe drives, you will get a reliable foundation for the stable and fast operation of your Kimai self-hosted solution, capable of scaling to meet the growing needs of your team.