Configurations

Configurations

• Configuration files
  • .env
  • local.yaml
  • Reload changed configurations
• System-configuration screen
• Data directory
• User preferences vs. system settings
• Adding system configuration

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 files

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.

.env

These “environment specific settings” are required so Kimai can boot. They are stored in the .env file:

• MAILER_URL - smtp connection for emails
• MAILER_FROM - application specific “from” address for all emails
• APP_ENV - environment for the runtime (use prod if 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)

local.yaml

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.

Reload changed configurations

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.

System-configuration screen

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 ROLE_SUPER_ADMIN.

Each setting in this screen can also be changed in the config file config/packages/local.yaml.

Data directory

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: eg. var/data/invoices/ for generated invoices.

The data directory can be changed by adapting the config key data_dir in your local.yaml:

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.

User preferences vs. system settings

A user has several preferences, which change the behaviour how he interacts with Kimai.

Check out the user preferences documentation to find out more.

Adding system configuration

As plugin developer you can add your own sections to the system configuration screen, see developer documentation.