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 when encrypting data (don’t change it after initial setup!)
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).
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 configurations by rebuilding the cache.
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.
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
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
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.
As plugin developer you can add your own sections to the system configuration screen, see developer documentation.