Kimai¶

Kimai is a free, open source time-tracking software written in PHP and designed for small businesses and freelancers.

The times tracked in the software can be directly priced, aggregated, invoiced and integrated in automated processes utilizing the RESTful API.

Note

For this guide you should be familiar with the basic concepts of

License¶

Kimai is released under the MIT License. All relevant information can be found in the LICENSE file in the repository of the project.

Prerequisites¶

We’re using PHP in the stable version 7.2. Since new Uberspaces are currently setup with PHP 7.1 by default you need to set this version manually:

[isabell@stardust ~]$ uberspace tools version use php 7.2
Selected PHP version 7.2
The new configuration is adapted immediately. Patch updates will be applied automatically.
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Your website domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation¶

To install Kimai we clone the current stable version using Git. cd to one level above your DocumentRoot so the cloned folder will live next to html.

Check the current stable release and copy the version number which you have to insert in the following git clone command.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ git clone -b 1.8 --depth 1 https://github.com/kevinpapst/kimai2.git
Cloning into 'kimai2'...
[…]
[isabell@stardust ~]$

Install all necessary dependencies using Composer. This can take some time.

[isabell@stardust isabell]$ cd kimai2/
[isabell@stardust kimai2]$ composer install --no-dev --optimize-autoloader
Loading composer repositories with package information
[…]
[isabell@stardust ~]$

Remove your unused DocumentRoot and create a new symbolic link to the kimai2/public directory:

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust isabell]$ rm -f html/nocontent.html; rmdir html
[isabell@stardust isabell]$ ln -s /var/www/virtual/$USER/kimai2/public html
[isabell@stardust ~]$

Configuration¶

To configure Kimai you need to edit the main configuration file /var/www/virtual/$USER/kimai2/.env. Open this file with a text editor of your choice.

Edit the following parts of your configuration file:

replace the secret in the line starting with APP_SECRET by a random string
comment out the line starting with DATABASE_URL=sqlite (prefix the line with a #)
comment in the line starting with DATABASE_URL=mysql (remove the #)
in the same line replace the placeholders db_user, db_password and db_name with your MySQL credentials
The finished configuration should look like this DATABASE_URL=mysql://isabell:SAFEPASSWORD@127.0.0.1:3306/isabell_kimai

Save the changed file and start the installation using the Kimai console.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/kimai2/
[isabell@stardust kimai2]$ bin/console kimai:install -n
Kimai installation running ...
[…]
[isabell@stardust ~]$

Finishing installation¶

Finish the installation by creating an admin user with the Kimai console. Insert your username and email address in the shell command. You will be prompted to insert a password afterwards.

Please don’t use admin as your username and set yourself a strong password.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/kimai2/
[isabell@stardust kimai2]$ bin/console kimai:create-user <username> <admin@example.com> ROLE_SUPER_ADMIN
Please enter the password: ****
[…]
[isabell@stardust ~]$

That’s it! You can now visit your website domain and login using your new account.

Best practices¶

Security¶

By default Kimai allows any visitor of your domain to register a new user account. You might want to disable that to prevent strangers in your Kimai instance. After disabling the anonymous registration you can still create new user accounts using the console.

Create a new configuration file called local.yml in config/packages/ and insert the following configuration:

kimai:
   user:
       registration: false

Save the new file and clear the cache so the changes become active.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/kimai2/
[isabell@stardust kimai2]$ bin/console cache:clear --env=prod
[isabell@stardust kimai2]$ bin/console cache:warmup --env=prod
[isabell@stardust ~]$

To be sure if everything works check if the registration link is gone from your login page.

Updates¶

Note

Check the update feed regularly to stay informed about the newest version.

Check Kimai’s releases for the latest versions. If a newer version is available, you should manually update your installation.

To update your installation fetch the new release tags from GitHub and checkout the version you want to update to by using their version number in the git checkout command. Afterwards update your dependencies with composer.

[isabell@stardust ~]$ cd /var/www/virtual/$USER/kimai2/
[isabell@stardust kimai2]$ git fetch --tags
[isabell@stardust kimai2]$ git checkout 1.8
[isabell@stardust kimai2]$ composer install --no-dev --optimize-autoloader
[isabell@stardust ~]$

Now clear and warmup your cache.

[isabell@stardust kimai2]$ bin/console cache:clear --env=prod
[isabell@stardust kimai2]$ bin/console cache:warmup --env=prod
[isabell@stardust ~]$

And last but not least: upgrade your database (you need to confirm the migration).

[isabell@stardust kimai2]$ bin/console doctrine:migrations:migrate
Application Migrations
WARNING! You are about to execute a database migration that could result in schema changes and data loss.
Are you sure you wish to continue? (y/n)
[isabell@stardust ~]$

Warning

It is possible that some version jumps require specific actions. Always check the UPGRADE guide and the release notes before updating your instance.

Tested with Kimai 1.8 and Uberspace 7.5.0

Written by: Daniel Kratz <https://danielkratz.com>