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 settingsconfig/packages/kimai.yaml
- examples for Kimai settingsconfig/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.
config/packages/kimai.yaml
) directly, as they will be overwritten during an update.
Adjust settings from any configuration file by adding them in your own configuration in local.yaml
(see below).
These “environment specific settings” are required so Kimai can boot. They are stored in the .env
file:
MAILER_URL
- smtp connection for emailsMAILER_FROM
- application specific “from” address for all emailsAPP_ENV
- environment for the runtime (always use prod
unless you want to develop for Kimai)DATABASE_URL
- database connection for storing all application dataAPP_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. touch config/packages/local.yaml
).
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.
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 config/packages/kimai.yaml
.
Inside the 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 data_dir
:
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 php.ini
).
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: ~
More infos in the Symfony docs and PHP documentation.
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/'
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 rates
configuration.
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
configurationkimai.calendar.google.sources
node, each must have its own name (like holidays
and company
in this example)kimai:
calendar:
google:
api_key: 'your-restricted-google-api-key'
sources:
holidays:
id: 'de.german#holiday@group.v.calendar.google.com'
color: '#ccc'
company:
id: 'de.german#holiday@group.v.calendar.google.com'
color: '#cc0000'