Installation
How to install Kimai on your server with git, composer and SSH or FTP
Self-hosting knowledge prerequisites
Self-hosting Kimai requires technical knowledge, including:
- Setting up and configuring servers and containers
- Managing application resources and scaling
- Securing servers and applications
- Configuring Kimai
Kimai recommends self-hosting for expert users. Mistakes can lead to data loss, security issues, and downtime. If you aren’t experienced at managing servers, Kimai recommends the hosted cloud.
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.24.0 is the latest stable release):
git clone -b 2.24.0 --depth 1 https://github.com/kimai/kimai.git
cd kimai/
Now install all dependencies:
composer install --no-dev --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
You might have to prefix the composer and installation commands with either php
or even the correct version:
php bin/console kimai:install -n
or php8.3 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/
You might not need these commands in a shared-hosting environment.
And you probably need to prefix them with sudo
and/or the group might be called different from 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 --no-dev --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. viabin/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 asroot
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.