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
Code language: CSS (css)

Enable and verify PHP:

sudo systemctl enable --now php8.2-fpm
php -v
php -m | grep -E 'mbstring|gd|intl|xml|zip'
Code language: JavaScript (javascript)

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
Code language: PHP (php)

4. Prepare Kimai Folder

sudo mkdir -p /var/www/kimai
sudo chown $USER:$USER /var/www/kimai
cd /var/www/kimai
Code language: PHP (php)

5. Clone Kimai Repo

git clone -b 2.35.1 --depth 1 https://github.com/kimai/kimai.git .
Code language: PHP (php)

6. Configure .env

cp .env.dist .env
nano .env
Code language: CSS (css)

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
Code language: JavaScript (javascript)

7. Install Dependencies

php8.2 $(which composer) install --no-dev --optimize-autoloader
Code language: JavaScript (javascript)

8. Run Kimai Installer

php8.2 bin/console kimai:install -n
Code language: JavaScript (javascript)

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 {} \;
Code language: JavaScript (javascript)

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;
    }
}
Code language: PHP (php)

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
Code language: JavaScript (javascript)

11. Secure with HTTPS

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d kimai.yourdomain.com
Code language: CSS (css)

Follow the prompts. After completion, test at:

https://kimai.yourdomain.com/
Code language: JavaScript (javascript)

12. Schedule Cron Jobs

sudo crontab -u www-data -e

Add this:

*/5 * * * * php8.2 /var/www/kimai/bin/console kimai:reload
Code language: JavaScript (javascript)

13. Create Your First Super Admin

Run:

php8.2 bin/console kimai:create-user
Code language: JavaScript (javascript)

Enter your details:

Username: youradmin
Email: [email protected]
Password: ********
Role: ROLE_SUPER_ADMIN
Code language: HTTP (http)

To remove the default admin:

php8.2 bin/console kimai:delete-user admin
Code language: JavaScript (javascript)

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

You’re All Set!