Self-hosted
User manual Developer Self-hosted
Installation, deactivating and uninstalling plugins

Plugin management

Table of contents

Kimai plugins are stored in var/plugins/, for example var/plugins/CustomCSSBundle/.

Plugin installation

Installation should be done with git clone or with a copy task.

Make sure that you copy it into the appropriate subdirectory in var/plugins/. For the plugin CustomCSSBundle this would be var/plugins/CustomCSSBundle/ (there should be a file var/plugins/CustomCSSBundle/CustomCSSBundle.php).

After the plugin was installed you need to clear the cache (see below).

Deactivate plugins

You can disable plugins by creating a file called .disabled in the plugin directory, e.g. var/plugins/CustomCSSBundle/.disabled.

You need to clear the cache afterwards (see below).

Plugin deinstallation

To uninstall a plugin, you simply have to delete the directory, e.g. var/plugins/CustomCSSBundle/.

Now clear the cache (see below).

Troubleshooting

There are three main reasons, why you might experience a 500 error after plugin installation:

  • You installed a plugin that is not compatible with your Kimai version
  • You forgot to change the file permissions after reloading the cache
  • You did not execute the necessary step to install the plugins database tables, the command is usually called bin/console kimai:bundle:example:install

Reload cache

How to reload Kimai cache

bin/console kimai:reload --env=prod

It is not advised, but in case the above command fails you could try:

rm -r var/cache/prod/*

Depending on your setup, the cache flush will create directories which cannot be written by your webserver:

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.