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.
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- 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 (use
prodif you are unsure)
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.
Read the cache documentation for more details.
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 can also be changed in the config file
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: eg.
var/data/invoices/ for generated invoices.
The data directory can be changed by adapting the config key
data_dir in your
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.
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.