Configurations

Environment specific settings (.env)
Config files
- Changing configurations
- Reload changed configurations
System-configuration screen
User preferences vs. system settings
Adding system configuration

This is an introduction into the configuration options and files, which are used by Kimai and an explanation on how to change them.

Specific configuration settings are explained in the respective documentation chapters.

Environment specific settings (.env)

The basic settings, which are required for Kimai to work are stored in the .env file:

MAILER_URL - smtp connection for emails
MAILER_FROM - application specific “from” address for all emails
APP_ENV - environment for the runtime (use prod if you are unsure)
DATABASE_URL - database connection for storing all application data
APP_SECRET - secret used when encrypting data (don’t change it after initial setup!)

Config files

Configuration of Kimai is done through the files in the config/ directory, the most important ones are:

.env - your environment and connection settings
config/packages/kimai.yaml - Kimai settings
config/packages/fos_user.yaml - user management
config/packages/local.yaml - additional Kimai configurations for your needs (file does not exist by default)

There are several other configurations that could potentially be interesting for you in config/packages/*.yaml.

If you want to adjust a setting from any of these files, apply them through the use of your own local.yaml (see below).

Changing configurations

You should NOT edit the file config/packages/kimai.yaml directly, as it contains default settings and will be overwritten during an update. Instead create the file config/packages/local.yaml and save your own settings in there. This file will NEVER be shipped with Kimai.

Having your custom settings in local.yaml allows you to easily update Kimai. This is the same concept which is used for the .env file.

An example config/packages/local.yaml file might look like this:

kimai:
    timesheet:
        rounding:
            default:
                begin: 15
                end: 15

admin_lte:
    options:
        default_avatar: build/apple-touch-icon.png

The local.yaml file will be imported as last configuration file, so you can overwrite any setting from the config/packages/ directory.

Whenever the documentation asks you to edit a yaml file from the config/packages/ directory, it means you should copy this specific configuration key to your local.yaml in order to overwrite the default configuration.

Be consistent with the indentation and don't mix spaces and tabs, YAML is very sensitive about that!

Reload changed configurations

When you change a configuration file, Kimai will not see this change immediately. You can reload the configurations by rebuilding the cache.

How to reload Kimai cache

bin/console kimai:reload

FTP users: please have a look at this documentation.

Before Kimai 1.8 you have to use:

bin/console cache:clear --env=prod
bin/console cache:warmup --env=prod

It might be necessary to execute these commands as webserver user, read the Installation docs for more details.

Depending on your setup and the way you call the cache command, you have to fix directory permissions afterwards.

Fix Kimai 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/
chmod -R g+rw public/avatars/

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.

System-configuration screen

You can edit most of the configurations from the Kimai UI directly.

This screen is only visible to users with the permission system_configuration which is by default given to ROLE_SUPER_ADMIN.

Each setting in this screen is also available in the config file (config/packages/kimai.yaml) where you might find additional information or links to the correct documentation chapter.

User preferences vs. system settings

A user has several preferences, which change the behaviour how he interacts with Kimai.

Check out the user preferences documentation to find out more.

Adding system configuration

As plugin developer you can add your own sections to the system configuration screen, see developer documentation.