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:
- 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
- Deploy the application:
docker-compose up -d
- Verify installation by visiting
http://<YOUR_SERVER_IP>:8001
in your browser.
π Manual Installation
For direct installation on a Linux server, follow these steps:
- Install dependencies:
sudo apt update && sudo apt install -y apache2 php php-mysql php-curl php-xml unzip mysql-server
- Clone the Kimai repository:
git clone https://github.com/kevinpapst/kimai2.git /var/www/kimai
- Set permissions:
sudo chown -R www-data:www-data /var/www/kimai
sudo chmod -R 775 /var/www/kimai/var
- 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;
- Install Kimai:
cd /var/www/kimai
composer install --no-dev --optimize-autoloader
bin/console kimai:install
- 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.
- 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;
}
}
- 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.
- Install Certbot:
sudo apt install certbot python3-certbot-nginx
- Obtain and configure the certificate:
sudo certbot --nginx -d yourdomain.com
- 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.
- Edit the
.env
file in your Kimai directory:
nano /var/www/kimai/.env
- Set
APP_ENV
todev
:
APP_ENV=dev
- 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.
- Edit the
.env
file:
nano /var/www/kimai/.env
- Set the API to active:
KIMAI_API_ENABLED=true
- 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.