The recommended way to install Kimai is via SSH, you need GIT and Composer.
To install Kimai in your production environment, connect with SSH to your server and change to your webservers (document) root directory. You need to install Git and Composer if you haven’t already.
First clone this repo (1.14.3 is the latest stable release):
git clone -b 1.14.3 --depth 1 https://github.com/kevinpapst/kimai2.git cd kimai2/
Now install all dependencies:
composer install --no-dev --optimize-autoloader
Configure the database connection in the
And run the Kimai installer:
bin/console kimai:install -n
The webserver needs write permissions for several directories, so make sure the file permissions are correct.
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):
Test Kimai before executing these commands (they are likely not required in a shared-hosting environment).
You probably need to prefix them with
the group might be called different than
There are several options to create your first user:
bin/console kimai:create-user username firstname.lastname@example.org ROLE_SUPER_ADMIN
If you are going to import data from Kimai v1 choose a username & email that was not used in v1.
Configure your web server (like Nginx or Apache) to point its DocumentRoot at the
For more details, see the Webserver How-To.
Oh … wait! Before you leave, please read the initial setup guide.
There is a dedicated article about Docker setups for Kimai, suitable for development and production.
The following platforms adopted Kimai to be compatible with their one-click installation systems.
Cloudron provides a secure and ready to use Kimai package, which will be kept up-to-date automatically.
Be aware that VestaCP uses the
admin user instead of
www-data. Replace the names in the permission commands above.
Read this issue if you have further questions.
CloudJiffy provides a scalable, hourly billed and easy to use PaaS platform and the setup of Kimai is only a click of a button away. Kimai is always deployed from the latest Github branch, thus you can rest easy that your software will always be up-to-date.
How to install Kimai at shared hosting companies. Please share our insights if you have managed to get it up and running with another company!
If you can’t find the correct version, ask your hoster! Or let us help you.
/usr/bin/php7.3-cli composer.phar install --no-dev --optimize-autoloader
/usr/bin/php7.3-cli bin/console kimai:install -n
curl -sS https://getcomposer.org/installer | php7.3.5-cli
php7.3.5-cli composer.phar install --no-dev --optimize-autoloader
php7.3.5-cli bin/console kimai:install -n
Strato has a special setup of PHP, you need to find the proper version first.
For example, if you want to use PHP 7.3 use always the absolute path when running a PHP based command: so prefix all commands with eg.
/opt/RZphp73/bin/php-cli in bash.
How to install Kimai:
curl -sS https://getcomposer.org/installer | /opt/RZphp73/bin/php-cli
/opt/RZphp73/bin/php-cli ../composer.phar install --no-dev --optimize-autoloader
.envfile, eg. with
/opt/RZphp73/bin/php-cli bin/console kimai:install -n
Reload your configuration
/opt/RZphp73/bin/php-cli bin/console kimai:reload
If a subdomain has not yet been added, login to the Plesk frontend and add a new subdomain, e.g. kimai.my-domain.com. Use the database tab of the new subdomain to create a new database for Kimai. Also check the selected PHP version for this subdomain in the development-tools section of the subdomain.
Next, the actual installation needs to be done in the command line of the webserver directly.
/opt/plesk/php. Depending on which PHP version was configured for Kimai subdomain, make sure to use this version during the installation. For example, if using version 7.3, the path to PHP should be
/var/www/vhosts/<domain_name>. For hosting location on Windows, please refer to official Plesk documentation:
curl -sS https://getcomposer.org/installer | /opt/plesk/php/7.3/bin/php
git clone -b 1.14.3 --depth 1 https://github.com/kevinpapst/kimai2.git
/opt/plesk/php/7.3/bin/php ../composer.phar install --no-dev --optimize-autoloader
.envfile to have correct database credentials
/opt/plesk/php/7.3/bin/php bin/console kimai:install -n
cd .. chown -R psacln:psaserv kimai2 chmod -R g+r kimai2 chmod -R g+rw kimai2/var/ chmod -R g+rw kimai2/public/avatars/
su -p user
cd kimai2 bin/console kimai:reload --env=prod
bin/console kimai:create-user username email@example.com ROLE_SUPER_ADMIN
/var/www/vhosts/my-domain.com/kimai2/public. Also ensure that
ServerAliasare set to
curl -sS https://getcomposer.org/installer | /usr/bin/php
php composer.phar install --no-dev --optimize-autoloader
php bin/console kimai:install -n
php bin/console kimai:reload
See issue #1620.
Installation via FTP is not supported. Kimai cannot be installed with FTP.
You have two choices:
That 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.
If you see an error message like this, then you have a special character in your
!! !! In DriverManager.php line 259: !! !! Malformed parameter "url". !!
This can be a character like
/ 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');" mG0%2Fd1%403aT.Z%29s
DATABASE_URL might look like this:
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.
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
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.
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 (
In that case, prefix them with
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:
var/log/prod.login your installation directory.
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
rootas well. Fix file permissions!
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.