The recommended way to install Kimai v2 is via SSH, you need GIT and Composer.
To install Kimai 2 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.0.1 is the latest stable release):
git clone -b 1.0.1 --depth 1 https://github.com/kevinpapst/kimai2.git cd kimai2/
Make sure the file permissions are correct (
www-data is an example, which works for Debian based distributions):
chown -R :www-data . chmod -R g+r . chmod -R g+rw var/
Configure the database connection in the
.env file (defaults to SQLite, but MySQL/MariaDB is recommended):
Now install all dependencies, you might have to do this as webserver user (prefix with
sudo -u www-data):
composer install --no-dev --optimize-autoloader
Create the database if you haven’t done it before with a DB administration tool (like PHPMyAdmin):
Create the required tables:
Set the initial database version, you will run into troubles during updates without that:
bin/console doctrine:migrations:version --add --all -n
Warm up the cache, you might have to do this as webserver user (prefix with
sudo -u www-data):
bin/console cache:warmup --env=prod
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 use a different username & email
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 2 to be compatible with their one-click installation systems.
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.
If you have no SSH access to your server (e.g. when you use a shared hosting package) then you can download a package, which includes a pre-installed Kimai version.
You install it via FTP like this:
var/data/kimai.sqlite will hold all your data, please include it in your backups.
Unfortunately there is no support for updates yet. This feature will be included in the future.
I know that you probably don’t have the technical background for managing a server yourself and need to rely on a shared hosting package. If you thought about switching to a managed server before (they are affordable these days) you can contact me, I offer paid setup support.
Clone the repository and install all dependencies:
git clone https://github.com/kevinpapst/kimai2.git cd kimai2/ composer install
Kimai uses a SQLite database by default, which will work out-of-the-box. But you have to change your
dev in your
.env file. You can also configure a MySQL database if you prefer that:
The next command will import demo data, to test the application in its full beauty - with different user accounts,
customers, projects, activities and several thousand timesheet records. Lets bootstrap your database
(command only available in
Finally you start a web server, you can access Kimai in your browser at http://127.0.0.1:8000/.
Stop the built-in web server by pressing
Ctrl + C while you’re in the terminal.
You can now login with these accounts:
Demo data can always be deleted by dropping the schema and re-creating it.
kimai:reset-dev command will do that automatically and can always be executed later on to reset your dev database and cache.
If you want to test with an empty installation, erase the database and re-create an empty schema:
bin/console doctrine:schema:drop --force bin/console doctrine:schema:create
To re-generate the frontend assets (more information here), execute:
yarn install npm run prod
SQLite is a great database engine for testing, but when it comes to production usage it is not recommended:
Kimai works around the Foreign Keys issue by using a Doctrine PostConnect EventSubscriber since v0.8.1, but it is not guaranteed that SQLite handles everything as expected.
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 2 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 2 and how your computer is configured, you may also receive
“operation not permitted” errors when setting file permissions (
In that case, prefix them with
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.