In this tutorial, we have covered step-by-step guide on how to install Kimai on a Debian 13. A self-hosted time-tracking application.

Kimai is popular among freelancers and businesses for its intuitive interface and powerful reporting tools. Each step below includes explanations so you understand not just what to do, but also why you’re doing it.

Prerequisites

• A Debian 13 installed dedicated server or KVM VPS.
• A root user or normal user with administrative privileges.
• A domain name point A record to server’s IP

How To Install Kimai on a Debian 13

1. Update and Prepare Your Server

Update Your Package List

Open your terminal or SSH into your Debian 13 server. It’s always a good practice to ensure that your server packages are up to date before installing any new software.

sudo apt updatesudo apt upgrade -y

The -y flag automatically confirms any prompts to install updates.

Install Basic Tools

While many of these might be installed by default, it’s good to be certain.

sudo apt install zip unzip curl -y

2. Install Apache (or Nginx)

Kimai runs on PHP, which needs a web server to handle requests. Apache is straightforward and widely used; you can also use Nginx if you prefer.

Install Apache

sudo apt install apache2 -y

• Installs the Apache web server on your Debian 13 server.
• After installation, Apache will automatically start running.

Check if Apache is Running

sudo systemctl status apache2

If it’s active (running), you’re good to go. If not, start it manually: sudo systemctl start apache2.

Enable Apache on Boot

sudo systemctl enable apache2

Ensures Apache automatically starts after a server reboot.

(If you prefer using Nginx, you would install it by running sudo apt install nginx -y and configure the virtual host accordingly. For simplicity, this guide focuses on Apache.)

3. Install and Configure PHP

Kimai requires PHP with several extensions. Debian 13 typically has a newer version of PHP (for example, PHP 8.x).

Install PHP and Required Extensions

sudo apt install php php-cli php-fpm php-common \php-gd php-intl php-mbstring php-mysql php-xml \php-zip php-curl php-ldap -y

• php-cli: Command-line interface for running PHP scripts.
• php-fpm: FastCGI process manager for PHP, helps with performance.
• php-mbstring: Needed for string manipulation in various encodings.
• php-mysql: Allows PHP to communicate with MySQL/MariaDB databases.
• php-intl: Important for internationalization and date formatting.
• php-xml, php-zip, php-curl, php-gd: Various functionalities that Kimai needs to generate PDFs, handle files, and manage HTTP requests.
• php-ldap: Required if you plan to integrate Kimai with an LDAP directory.

Adjust PHP Settings

Open the main PHP configuration file or the relevant pool file (often found at /etc/php/8.4/apache2/php.ini) in your favorite text editor:

sudo nano /etc/php/8.4/apache2/php.ini

Look for these settings and adjust them if necessary (for example, increasing the maximum file upload size or memory limit):

memory_limit = 256Mupload_max_filesize = 50Mpost_max_size = 50M

• memory_limit controls how much memory a PHP script can use.
• upload_max_filesize and post_max_size control allowed file upload sizes.

Restart Apache

sudo systemctl restart apache2

Applies any configuration changes immediately.

4. Install MariaDB (or MySQL) and Create a Database

Kimai stores its data (projects, timesheets, user info, etc.) in a database. MariaDB is a popular open-source fork of MySQL.

Install MariaDB

sudo apt install mariadb-server mariadb-client -y

Secure Your MariaDB Server

sudo mysql_secure_installation

You’ll be prompted to set a root password, remove anonymous users, disable remote root login, and more. These steps help secure your database.

Create a Database and User for Kimai

Log into the MariaDB shell:

sudo mysql

Inside the MariaDB shell, run the following queries (adjust values to match your preferences here we use kimai_db, kimai_user, and StrongPassword as placeholders):

CREATE DATABASE kimai_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;CREATE USER 'kimai_user'@'localhost' IDENTIFIED BY 'StrongPassword';GRANT ALL PRIVILEGES ON kimai_db.* TO 'kimai_user'@'localhost';FLUSH PRIVILEGES;EXIT;

• kimai_db: The new database’s name.
• kimai_user: The username for the Kimai database user.
• StrongPassword: A secure password for that user.

5. Install Composer (PHP Dependency Manager)

Composer is critical because Kimai’s dependencies—such as libraries and frameworks—are managed using Composer.

Download and Install Composer

curl -sS https://getcomposer.org/installer -o composer-setup.phpphp composer-setup.php --install-dir=/usr/local/bin --filename=composer

Downloads Composer’s installer script.

Installs Composer globally to /usr/local/bin, naming it composer.

Verify Composer is Working

composer --version

You should see the installed version printed in your terminal.

6. Download and Install Kimai

Now that we have PHP, Composer, and MariaDB set up, we can install Kimai.

Navigate to a Web-Accessible Directory

Typically, Apache’s default web root is /var/www/html.

cd /var/www/html

(If you prefer a different directory, adjust commands accordingly.)

Download Kimai

You can clone from GitHub or download a release package. The official stable releases are recommended for production. Here’s a method using Git:

sudo apt install git -ygit clone -b 2.45.0 --depth 1 https://github.com/kimai/kimai.git

This will create a kimai folder inside /var/www/html.

Install Kimai’s Dependencies

cd kimaisudo composer install --no-dev --optimize-autoloader

• –no-dev: Installs only the dependencies needed for production (excluding development/test packages).
• –optimize-autoloader: Improves performance by optimizing how PHP classes are loaded.

Set Proper Permissions

Kimai needs certain folders to be writable by the web server user (often www-data):

sudo chown -R www-data:www-data /var/www/html/kimaisudo chmod -R 755 /var/www/html/kimai

• chown: Changes the owner of the files to the web server user.
• chmod: Adjusts file permissions so they are readable and executable.

7. Configure Kimai

Kimai needs to know how to connect to your database and how to handle encryption.

Create the Kimai Environment File

Copy the default configuration and then customize it:

cp .env.dist .envnano .env

Look for the database configuration line (it might look like this):

DATABASE_URL=mysql://kimai_user:StrongPassword@127.0.0.1:3306/kimai_db

Update it with your actual database name, user, and password.

Generate Encryption Keys

Kimai uses Symfony’s console commands to manage setup tasks.

sudo -u www-data php bin/console kimai:install -n

• -n: Non-interactive mode (it won’t ask for confirmation).

This command also creates the necessary database tables based on your .env file settings.

Create an Admin User

If the above command didn’t prompt you to create a user, you can do it separately:

bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN

• Replace username and admin@example.com with your choices.
• You’ll be asked to provide a password.

8. Configure Apache Virtual Host

Now we tell Apache how to serve Kimai from a domain or a subdomain.

Create a Virtual Host File

sudo nano /etc/apache2/sites-available/kimai.conf

Insert the following (adjust the ServerName and paths to your environment):

<VirtualHost *:80>    ServerName kimai.example.com    DocumentRoot /var/www/html/kimai/public    <Directory /var/www/html/kimai/public>        AllowOverride All        Require all granted    </Directory>    ErrorLog ${APACHE_LOG_DIR}/kimai_error.log    CustomLog ${APACHE_LOG_DIR}/kimai_access.log combined</VirtualHost>

DocumentRoot /var/www/html/kimai/public points to the public folder where Kimai’s main index.php resides.

The AllowOverride All directive enables .htaccess usage, which Kimai relies on for routing.

Enable the New Virtual Host and Rewrite Module

sudo a2ensite kimai.confsudo a2enmod rewritesudo systemctl restart apache2

• a2ensite kimai.conf: Tells Apache to use this new site configuration.
• a2enmod rewrite: Ensures URL rewriting is enabled (necessary for clean URLs).

9. Configure firewall

We need to allow HTTP and HTTPS ports in firewall.

ufw allow 80/tcpufw allow 443/tcp

10. Install SSL certification

To access application using HTTPS, we need to install SSL certification. We are using Let’s Encrypt Certbot to install the SSL certification.

sudo apt install certbot python3-certbot-apache

Now, let’s obtain the certification using following command (replace kimai.example.com):

sudo certbot --apache -d kimai.example.com

11. Logging into Kimai

Navigate to Kimai in a Web Browser

Go to https://kimai.example.com

Enter Admin Credentials. Use the admin username and password you created earlier.

Explore the Dashboard. From here, you can create projects, start time recordings, and add additional users if needed.

Common Post-Installation Steps

Configure Email: Kimai can send invoices and notifications by email. To configure it, edit your .env file to include your mail server details (SMTP credentials).

Set up Backups: Regularly back up your database and the Kimai directory. This ensures no data loss if something happens to your server.

Update Kimai: Occasionally check for new releases. Updating is usually as simple as pulling the latest code and running composer install –no-dev –optimize-autoloader. Always back up before updating.

Final Thoughts

We have seen how to install Kimai on a Debian 13. By following the steps above, you prepared your server, set up Apache, PHP, and MariaDB, installed Kimai with Composer, and configured your environment so it’s ready for production use. Kimai gives freelancers, teams, and companies a straightforward way to track work hours, generate reports, and bill clients all while you retain full control over your data on your own server.

Enjoy using Kimai for efficient time-tracking and project management!