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.
The basic settings, which are required for Kimai to work are stored in the
MAILER_URL- smtp connection for emails
MAILER_FROM- application specific “from” address for all emails
APP_ENV- environment for the runtime (use
prodif you are unsure)
DATABASE_URL- database connection for storing all application data
APP_SECRET- secret used for hashing user passwords (don’t change it, if you have user accounts in your database)
Configuration of Kimai is spread in all files in the
config/directory but mainly it these files:
.env- environment specific settings
config/packages/kimai.yaml- Kimai specific settings
config/packages/admin_lte.yaml- Kimai base theme
config/packages/fos_user.yaml- user management and email settings
config/packages/local.yaml- your configuration settings (file needs to be created by yourself)
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, use
local.yaml (see below).
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
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
local.yaml file will be imported as last configuration file, so you can overwrite any setting from the
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.
When you change a configuration file, Kimai will not see this change immediately. You can reload the configs after you are done by rebuilding the Symfony cache with:
bin/console cache:clear --env=prod bin/console cache:warmup --env=prod
Depending on your setup it might be necessary to execute these commands as webserver user, please read the Installation docs for more details.
With version 0.9 a new system configuration screen was introduced. This screen allows you to change some of the most important configurations directly from within Kimai.
This screen is only visible to users with the permission
system_configuration which is by default given to
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.
A user has several preferences, which change the behaviour how he interacts with Kimai.
Check out the user preferences documentation to find out more.