This is an introduction into the configuration files used by Kimai, and an explanation on how to change them.
Specific configuration settings are explained in the respective documentation chapters.
The most important configuration files of Kimai are:
.env- your environment and connection settings
config/packages/kimai.yaml- examples for Kimai settings
config/packages/local.yaml- configure your own Kimai settings (does not exist by default)
There are several other configurations that could potentially be interesting for you in config/packages/*.yaml.
These “environment specific settings” are required so Kimai can boot. They 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 (always use
produnless you want to develop for Kimai)
DATABASE_URL- database connection for storing all application data
APP_SECRET- secret used to encrypt session cookies (users will be logged out if you change it)
The configuration file
config/packages/local.yaml will NEVER be shipped with Kimai,
you have to create it before you change settings the first time (eg.
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 your
local.yaml configuration file, Kimai will not see this change immediately.
You have to reload the configurations by rebuilding the cache.
Many of the available configurations can be configured through System > Settings, all configuration which can be set through the UI will not be described here.
Examples for all available configuration can be found in
data directory Kimai and plugins will store newly created files.
This location is by default
var/data/, while files will be managed in sub-directories: e.g.
var/data/invoices/ for generated invoices.
The data directory can be changed by adapting the config key
kimai: data_dir: "/home/kimai/safe-place/"
After changing the data directory, you should move all existing data to the new location and then reload the cache.
By default, Kimai uses the PHP session lifetime configured on your server (normally in
If you want to change the session lifetime (eg. to prevent automatic logout during the workday or to prevent CSRF errors), you can either adjust the settings for PHP directly (see PHP docs) or you can explicitly set it for Kimai:
framework: session: gc_maxlifetime: 3600 cookie_lifetime: 3600
The values above (here
3600) are seconds, the above configuration would be rather strict and automatically logout the user after 1 hour.
Another example, where the session should last 10 hours with a session cookie that is deleted upon browser restart (every browser restart forces a new login):
framework: session: gc_maxlifetime: 36000 cookie_lifetime: ~
If you want to store your invoice templates in another location add this:
kimai: invoice: # add a new search location documents: - 'var/my_invoices/'
You could even deactivate all default templates and only show your own ones (this shouldn’t be necessary in 99% of all use-cases):
kimai: invoice: # disable the default locations defaults: ~ # add a new search location documents: - 'var/my_invoices/'
If you want/need to replace some default translations (e.g. they don’t reflect your industry), then you can add a translation file which will used as first translation source.
First you create a file
my-company.en.xlf either in the
translations/ directory or in
the translation directory of your custom plugin at
You activate the new translation file with:
kimai: theme: branding: translation: my-company
At System > Settings you can configure one rounding rule. The local.yaml allows adding multiple rules (e.g. weekend has different rounding rules). You can define as many rules as you want (“default” is only an example) and every matching rule will be applied (be careful with overlapping rules).
This examples rounds any weekend work up to 1 hour, while normal weekday work will round the end up to the next full 10 minutes slot:
kimai: timesheet: rounding: weekend: days: ['saturday','sunday'] begin: 1 end: 1 duration: 60 mode: closest workdays: days: ['monday','tuesday','wednesday','thursday','friday','saturday','sunday'] begin: 10 end: 10 duration: 0 mode: default
If you want to apply different hourly rates multiplication
factor for specific weekdays, you can use this
kimai: timesheet: rates: workdays: days: ['monday','tuesday','wednesday','thursday','friday'] factor: 1 weekend: days: ['saturday','sunday'] factor: 1.5
If you want to embed Google calendars e.g. to display regional holidays or company events you can import (multiple) Google calendars, which will be displayed in each of the user calendar.
kimai.calendar.google.sourcesnode, each must have its own name (like
companyin this example)
kimai: calendar: google: api_key: 'your-restricted-google-api-key' sources: holidays: id: 'firstname.lastname@example.org' color: '#ccc' company: id: 'email@example.com' color: '#cc0000'