Kimai: The Full Guide to Self-Hosting Anywhere

Kimai is an open-source, self-hosted time-tracking application designed for developers, teams, and organizations to effectively manage projects, track working hours, and generate reports. It’s an excellent choice for self-hosting due to its flexibility, data control, and ability to integrate with various tools via APIs. This guide will walk you through the process of deploying, configuring, and managing Kimai, ensuring a smooth experience with actionable steps tailored to its unique features.

Installing Kimai

📦 Docker/Docker Compose Setup

Kimai provides an official Docker image, making deployment straightforward and scalable. Here’s how to set it up using Docker Compose:

1. Create a docker-compose.yml file:

version: '3.4'

services:

kimai:

image: kimai/kimai2:latest

container_name: kimai

ports:

- "8001:8001"

volumes:

- ./kimai:/opt/kimai

- ./mysql:/var/lib/mysql

environment:

- APP_ENV=prod

- DATABASE_URL=mysql://kimai:kimai@db/kimai

db:

image: mysql:5.7

container_name: kimai_db

environment:

MYSQL_ROOT_PASSWORD: rootpassword

MYSQL_DATABASE: kimai

MYSQL_USER: kimai

MYSQL_PASSWORD: kimai

volumes:

- ./mysql:/var/lib/mysql

2. Deploy the application:

docker-compose up -d

3. Verify installation by visiting http://<YOUR_SERVER_IP>:8001 in your browser.

🚀 Manual Installation

For direct installation on a Linux server, follow these steps:

1. Install dependencies:

sudo apt update && sudo apt install -y apache2 php php-mysql php-curl php-xml unzip mysql-server

2. Clone the Kimai repository:

git clone https://github.com/kevinpapst/kimai2.git /var/www/kimai

3. Set permissions:

sudo chown -R www-data:www-data /var/www/kimai

sudo chmod -R 775 /var/www/kimai/var

4. Configure the database:

mysql -u root -p

CREATE DATABASE kimai CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'kimai'@'localhost' IDENTIFIED BY 'kimai_password';

GRANT ALL PRIVILEGES ON kimai.* TO 'kimai'@'localhost';

FLUSH PRIVILEGES;

5. Install Kimai:

cd /var/www/kimai

composer install --no-dev --optimize-autoloader

bin/console kimai:install

6. Access Kimai through your browser at http://<YOUR_SERVER_IP>.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Set up Nginx to route traffic to Kimai for better performance and flexibility.

1. Create an Nginx configuration file:

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

Add the following content:

server {

listen 80;

server_name yourdomain.com;

location / {

proxy_pass http://localhost: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;

}

}

2. Enable the site and test the configuration:

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

sudo nginx -t

sudo systemctl reload nginx

🔒 SSL/TLS Setup

Secure your Kimai installation with Let's Encrypt.

1. Install Certbot:

sudo apt install certbot python3-certbot-nginx

2. Obtain and configure the certificate:

sudo certbot --nginx -d yourdomain.com

3. Automate certificate renewals:

sudo crontab -e

0 3 * * * certbot renew --quiet

Logging and Debugging Kimai

🗃️ Enabling Debug Logs

Enable debug logs to gather detailed troubleshooting information.

1. Edit the .env file in your Kimai directory:

nano /var/www/kimai/.env

2. Set APP_ENV to dev:

APP_ENV=dev

3. Save and restart Kimai:

systemctl restart apache2

📄 Viewing Logs

Access logs to monitor activity and identify issues.

• For Docker installations:

docker logs kimai

• For manual installations:

tail -f /var/www/kimai/var/log/prod.log

🛠️ Troubleshooting Common Issues

Check for common errors like database misconfigurations or permission issues by analyzing logs. Example:

• Database connection errors:

grep 'database' /var/www/kimai/var/log/prod.log

📤 Exporting Logs

Forward logs to an external system like the ELK Stack by configuring filebeat or similar tools.

Backup and Restore

🗂️ File-Based Backups

Create a snapshot of Kimai’s directory:

tar -czvf kimai_backup_$(date +%F).tar.gz /var/www/kimai

🔄 Database Backups

Export your Kimai database:

mysqldump -u kimai -p kimai > kimai_db_backup.sql

Restore the database:

mysql -u kimai -p kimai < kimai_db_backup.sql

📅 Automated Backup Scripts

Automate backups using cron:

crontab -e

0 2 * * * tar -czvf /backup/kimai_$(date +%F).tar.gz /var/www/kimai && mysqldump -u kimai -p'kimai_password' kimai > /backup/kimai_$(date +%F).sql

Updating and Upgrading Kimai

⬆️ Updating Docker Images

For Docker users, pull the latest image and redeploy:

docker-compose pull

docker-compose down

docker-compose up -d

🛠️ Manual Updates

For manual installations, update the codebase:

cd /var/www/kimai

git pull origin main

composer install --no-dev --optimize-autoloader

bin/console kimai:update

🔍 Checking for Updates

Stay informed about updates by following Kimai’s GitHub repository and changelogs.

Leveraging Kimai’s Unique Features

🔧 Enabling APIs

Activate and test Kimai’s REST API for integrations.

1. Edit the .env file:

nano /var/www/kimai/.env

2. Set the API to active:

KIMAI_API_ENABLED=true

3. Test the API with curl:

curl -X GET -H "X-AUTH-TOKEN: <your_api_token>" http://yourdomain.com/api/users

🌟 Advanced Configurations

Customize Kimai for your needs, such as enabling plugins or tweaking configurations. For example:

• Add plugins to /var/www/kimai/plugins/ and restart the app.

Wrapping Up

In this guide, we covered the essential steps to deploy, configure, and manage Kimai, from installation and Nginx setup to logging, backups, and leveraging its unique features. Kimai’s flexibility and control make it an invaluable tool for tracking time and managing projects. Begin implementing these steps today to unlock its full potential and streamline your workflows.