Installation

How to install Kimai on your server with git, composer and SSH or FTP

Server requirements

PHP 8.1+ with the extensions: mbstring, gd, intl, json, pdo, tokenizer, xml, zip
Database: MariaDB or MySQL
Webserver (NGINX, or Apache with mod_rewrite)
A modern web browser
A free subdomain (use in subdirectory is not supported)
You need to install Git and Composer if you haven't already

Install Kimai with SSH

To install Kimai in your environment, connect with SSH to your server and change to your webservers (document) root directory.

First clone this repo (2.15.0 is the latest stable release):

git clone -b 2.15.0 --depth 1 https://github.com/kimai/kimai.git
cd kimai/

Now install all dependencies:

composer install --optimize-autoloader

Configure the database connection and server version in the .env file:

DATABASE_URL=mysql://user:password@127.0.0.1:3306/database?charset=utf8mb4&serverVersion=11.1.2-MariaDB

Fetch the exact serverVersion by running mysql --version and copy&paste the entire version.

And run the Kimai installer:

bin/console kimai:install -n

Windows users might have to prefix the composer and installation commands with php, eg.:
php bin/console kimai:install -n

File permissions

The webserver needs write permissions for several directories, so make sure the file permissions are correct.

Adjust file permission

You have to allow PHP (your webserver process) to write to var/ and it subdirectories.

Here is an example for Debian/Ubuntu (to be executed inside the Kimai directory):

chown -R :www-data .
chmod -R g+r .
chmod -R g+rw var/

Test Kimai before executing these commands (they are likely not required in a shared-hosting environment). You probably need to prefix them with sudo and the group might be called different than www-data.

Create your first user

There are several options to create your first user:

via command: bin/console kimai:user:create username admin@example.com ROLE_SUPER_ADMIN
via login screen: you can register a user, the first one will be promoted to the role ROLE_SUPER_ADMIN
you can configure LDAP or SAML for authentication

If you are going to import data from Kimai v1 choose a username & email that was not used in v1.

Configure DocumentRoot

Configure your web server (like nginx or Apache) to point its DocumentRoot at the public/ directory. For more details, see the Webserver How-To.

Oh … wait! Before you leave, please read the initial setup guide.

Other installation methods

Docker

There is a dedicated article about running a Docker image of Kimai, suitable for development and production.

Kubernetes

The rise of containerization and orchestration is not stopping, please read the Kubernetes and Helm chart chapter to find out more.

Shared hosting

Kimai is known to be compatible and can be installed on a wide range of shared hosting environments like Uberspace, 1&1, ionos, Domainfactiry, All-Inkl, Strato and others.

1-click installations

Many platforms adopted Kimai to be compatible with their 1-click installation systems, like YunoHost, Softaculous, Cloudron, VestaCP, ISPConfig 3 and Cloudjiffy.

Plesk

Hosting Kimai on Plesk is described in the shared hosting article.

FTP installation

Installation via FTP is not supported, because most of Kimai's management tasks rely on the console.

You have two choices:

get a proper webhosting/virtual server with SSH support
use a SaaS time-tracking software

If you don’t have the technical background for managing a server yourself and need to rely on a shared hosting package, it is better to stop hosting business critical software yourself! If you thought about switching to a managed server before (they are affordable these days) you can contact me, I offer paid setup support.

Ansible

Webarchitects Co-operative have written a Kimai Ansible Galaxy role for automatically installing and upgrading Kimai sites on their shared hosting servers.

Installation FAQ

Column ‘TABLE_NAME’ in where clause is ambiguous

An error like this might occur when you have a misconfigured serverVersion in your DATABASE_URL:

[ERROR] Failed to set migration status: An exception occurred while executing a query: SQLSTATE[23000]: Integrity
constraint violation: 1052 Column 'TABLE_NAME' in where clause is ambiguous

Run mysql --version and extract the entire version string, for example for this version string:

mysql from 11.1.2-MariaDB, client 15.2 for osx10.19 (arm64) using  EditLine wrapper

the serverVersion part in your DATABASE_URL should include the part 11.1.2-MariaDB like this:

DATABASE_URL=mysql://kimai:kimai@sqldb/kimai?charset=utf8mb4&serverVersion=11.1.2-MariaDB

MySQL server has gone away

The message SQLSTATE[HY000] [2006] MySQL server has gone away usually means that your DATABASE_URL is wrong. You can run a command like bin/console doctrine:schema:validate to check, if the software can connect successfully to your database.

If that gives you the same error, it is configuration issue which you need to solve first, before you are able to install Kimai.

Malformed parameter “url”

If you see an error message like this, then you have a special character in your DATABASE_URL.

!!  
!!  In DriverManager.php line 259:
!!                                
!!    Malformed parameter "url".  
!!

This can be a character like @ or / or some others, which need to be urlencoded. This can easily be done with one command, lets assume your password is mG0/d1@3aT.Z)s then you get your password like this:

php -r "echo urlencode('mG0/d1@3aT.Z)s');echo PHP_EOL;"
mG0%2Fd1%403aT.Z%29s

Then your DATABASE_URL might look like this:

DATABASE_URL=mysql://root:mG0%2Fd1%403aT.Z%29s@127.0.0.1:3306/kimai2?charset=utf8mb4&serverVersion=8.3.0

Which user to use, www-data, httpd or your own?

The installation instructions are intended primarily for server applications.

If you are installing Kimai on your personal computer - maybe for use in a local network, but where the computer primarily serves as a single user computer - you will avoid permission errors by substituting www-data in the relevant commands with your username.

In particular, sudo -u www-data is a command which grants the www-data user temporary administrator/super-user privileges). However, depending on the configuration of your particular computer, you may be able to avoid sudo altogether (your user may already have adequate permissions). Or your webserver user is not called www-data but httpd.

You can try first leaving sudo -u www-data altogether in the relevant commands. If you have permission errors, you can substitute it for sudo -u $USER in the relevant commands, where username is the username that runs the server - if you don’t know, it is likely your own username that you login with.

chown & chmod commands

Further, chown and chmod commands should be for the username that runs the server instead of www-data (again, if you don’t know, it is likely your own username).

Also note that, depending on where you are installing Kimai and how your computer is configured, you may also receive “operation not permitted” errors when setting file permissions (chown and chmod commands). In that case, prefix them with sudo.

Memory limit

Composer crashes with something like

!!    Error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 20480 bytes)

Then please read this chapter in the official docs. In short, try to run:

COMPOSER_MEMORY_LIMIT=-1 php -d memory_limit=-1 /usr/bin/composer install --optimize-autoloader

Internal Server Error 500

This error can have several causes. Here is a small summary what to check for if this error occurs when trying to access the Kimai frontend:

There could be something wrong with your file permissions. Please check the log var/log/prod.log in your installation directory.
Make sure not to reload Kimai as root (e.g. via bin/console kimai:reload --env=prod). The application will create folders and files. If root started the process you most likely will have permission errors if the web-server is not started as root as well. Fix file permissions!

Still doesn’t work?

These infos were added to give you some possible guidance if you run into troubles. The Linux (and Mac) filesystem with its permission structure, especially when using server software, can be tricky and challenging.

But this has NOTHING to do with Kimai and we might not be able to help you in such situations … it is your system and responsibility, be aware that wrong permissions might break Kimai and can also lead to security problems.