Hey there! If you’re looking to set up Kimai 2—the awesome open-source time-tracking tool—on your Debian 12 server, you’re in the right place. We’ll keep things casual and walk through each step like you’re having a chat over coffee. By the end, your Kimai instance will be up and running with PHP 8.2, Nginx, and Let’s Encrypt HTTPS. Ready? Let’s dive in.
Note: We assume your database (MariaDB or MySQL) is already set up. If not, check out the guide on installing MariaDB on Debian 12 first.
1. Meet Your Server Prereqs
Before we get our hands dirty, make sure you have:
- SSH access with a sudo-capable user
- PHP 8.2 with required extensions
- MariaDB or MySQL up and running
- Nginx as your web server
- Git & Composer installed
- A domain (e.g., kimai.yourdomain.com) pointed to your server
- Firewall open on ports 22 (SSH), 80 (HTTP), and 443 (HTTPS)
2. Install PHP 8.2 and Extensions
|
0 1 2 3 4 5 |
sudo apt update sudo apt install -y php8.2 php8.2-cli php8.2-fpm \ php8.2-mbstring php8.2-gd php8.2-intl php8.2-xml \ php8.2-zip php8.2-curl php8.2-opcache php8.2-mysql |
Enable and verify PHP:
|
0 1 2 3 4 |
sudo systemctl enable --now php8.2-fpm php -v php -m | grep -E 'mbstring|gd|intl|xml|zip' |
3. Get Git and Composer
|
0 1 2 3 4 5 6 7 8 9 |
sudo apt install -y git curl unzip cd /tmp curl -sS https://getcomposer.org/installer | php sudo mv composer.phar /usr/local/bin/composer # Check versions git --version composer --version |
4. Prepare Kimai Folder
|
0 1 2 3 4 |
sudo mkdir -p /var/www/kimai sudo chown $USER:$USER /var/www/kimai cd /var/www/kimai |
5. Clone Kimai Repo
|
0 1 2 |
git clone -b 2.35.1 --depth 1 https://github.com/kimai/kimai.git . |
6. Configure .env
|
0 1 2 3 |
cp .env.dist .env nano .env |
Edit the DATABASE_URL line with your actual DB credentials. For example:
|
0 1 2 |
DATABASE_URL=mysql://kimai_user:[email protected]:3306/kimai2?charset=utf8mb4&serverVersion=11.1.2-MariaDB |
7. Install Dependencies
|
0 1 2 |
php8.2 $(which composer) install --no-dev --optimize-autoloader |
8. Run Kimai Installer
|
0 1 2 |
php8.2 bin/console kimai:install -n |
9. Set File Permissions
|
0 1 2 3 4 |
sudo chown -R www-data:www-data var/ sudo find var/ -type d -exec chmod 770 {} \; sudo find var/ -type f -exec chmod 660 {} \; |
10. Configure Nginx
10.1 Install Nginx
|
0 1 2 |
sudo apt install -y nginx |
10.2 Nginx Site Config
Create /etc/nginx/sites-available/kimai.conf:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
server { listen 80; server_name kimai.yourdomain.com; root /var/www/kimai/public; index index.php; access_log /var/log/nginx/kimai_access.log; error_log /var/log/nginx/kimai_error.log; location / { try_files $uri /index.php$is_args$args; } location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.2-fpm.sock; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; fastcgi_param DOCUMENT_ROOT $realpath_root; internal; } location ~* \.(?:css|js|jpg|jpeg|gif|png|svg|woff2|woff|ttf|ico)$ { expires 1M; access_log off; add_header Cache-Control "public"; } location ~ /\.ht { deny all; } } |
Enable the site:
|
0 1 2 3 4 5 |
sudo ln -s /etc/nginx/sites-available/kimai.conf /etc/nginx/sites-enabled/ sudo rm /etc/nginx/sites-enabled/default sudo nginx -t sudo systemctl reload nginx |
11. Secure with HTTPS
|
0 1 2 3 |
sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d kimai.yourdomain.com |
Follow the prompts. After completion, test at:
|
0 1 2 |
https://kimai.yourdomain.com/ |
12. Schedule Cron Jobs
|
0 1 2 |
sudo crontab -u www-data -e |
Add this:
|
0 1 2 |
*/5 * * * * php8.2 /var/www/kimai/bin/console kimai:reload |
13. Create Your First Super Admin
Run:
|
0 1 2 |
php8.2 bin/console kimai:create-user |
Enter your details:
|
0 1 2 3 4 5 |
Username: youradmin Email: admin@example.com Password: ******** Role: ROLE_SUPER_ADMIN |
To remove the default admin:
|
0 1 2 |
php8.2 bin/console kimai:delete-user admin |
14. Maintenance Tips
- Update regularly:
sudo apt update && sudo apt upgrade -y - Backup MariaDB daily:
mysqldump -u root -p kimai2 | gzip > /backup/kimai2_$(date +%F).sql.gz - Monitor logs:
var/log/and/var/log/nginx/ - Consider Supervisor or systemd for advanced task handling
- Check out Kimai plugins to expand features