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
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:
sudo systemctl enable --now php8.2-fpm
php -v
php -m | grep -E 'mbstring|gd|intl|xml|zip'
3. Get Git and Composer
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
sudo mkdir -p /var/www/kimai
sudo chown $USER:$USER /var/www/kimai
cd /var/www/kimai
5. Clone Kimai Repo
git clone -b 2.35.1 --depth 1 https://github.com/kimai/kimai.git .
6. Configure .env
cp .env.dist .env
nano .env
Edit the DATABASE_URL line with your actual DB credentials. For example:
DATABASE_URL=mysql://kimai_user:[email protected]:3306/kimai2?charset=utf8mb4&serverVersion=11.1.2-MariaDB
7. Install Dependencies
php8.2 $(which composer) install --no-dev --optimize-autoloader
8. Run Kimai Installer
php8.2 bin/console kimai:install -n
9. Set File Permissions
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
sudo apt install -y nginx
10.2 Nginx Site Config
Create /etc/nginx/sites-available/kimai.conf:
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:
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
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d kimai.yourdomain.com
Follow the prompts. After completion, test at:
https://kimai.yourdomain.com/
12. Schedule Cron Jobs
sudo crontab -u www-data -e
Add this:
*/5 * * * * php8.2 /var/www/kimai/bin/console kimai:reload
13. Create Your First Super Admin
Run:
php8.2 bin/console kimai:create-user
Enter your details:
Username: youradmin
Email: [email protected]
Password: ********
Role: ROLE_SUPER_ADMIN
To remove the default admin:
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