kimai2/var/docs/configurations.md

Configurations

Environment specific settings (.env)

The most basic settings, which need always be adjusted 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
• DATABASE_PREFIX - precix for any Kimai table in the configured database
• APP_SECRET - secret used for hasing user password (if you cahnge this, every password is invalid afterwards)

Config files

Configuration of Kimai is spread in all files in the config/directory but mainly it these files:

• .env - environment specific settings
• config/packages/kimai.yaml - Kimai specific settings
• config/packages/admin_lte.yaml - Kimai base theme
• config/packages/fos_user.yaml - user management and email settings
• config/packages/local.yaml - your local configuration settings

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, use local.yaml (see below).

Other topics

• Theme settings - in kimai.yaml and admin_lte.yaml
• Email configuration - in swiftmailer.yaml
• Dashboard widgets - in kimai.yaml
• Calendar - in kimai.yaml
• Invoices - in kimai.yaml

Overwriting local configs (local.yaml)

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 store 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 .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 a configuration file, Kimai will not see this change immediately. You can reload the configs after you are done by rebuilding the Symfony cache with:

bin/console cache:clear --env=prod
bin/console cache:warmup --env=prod

Depending on your setup it might be necessary to execute these commands as webserver user, please read the UPGRADING guide for more details.

Security

Kimai uses the FOSUserBundle for security related tasks like user management. Its configuration can be found in fos_user.yaml.

User management emails (fos_user.yaml)

Read more about email configuration.

Remember me login (security.yaml)

The default period for the Remember me option can be changed in the config file security.yaml.

User registration

If you want your new users to use email based activation add this to your local.yaml:

fos_user:
    registration:
        confirmation:
            enabled: true

Disable user registration

If you want to disable the user registration, add this your local.yaml:

kimai:
    user:
        registration: false

If you only want to hide the link from the login form but keep the functionality, add this your local.yaml:

admin_lte:
    routes:
        adminlte_registration: ~

Password reset

If you want to configure the behaviour (like the allowed time between multiple retries) then configure the settings:

• in config/packages/fos_user.yaml the key below fos_user.registration.resetting (see documentation)
• the values retry_ttl and token_ttl are configured in seconds (7220 = 2 hours)

Disable password reset

If you want to disable the password reset, add this your local.yaml:

kimai:
    user:
        password_reset: false

If you only want to hide the link from the login form but keep the functionality, add this your local.yaml:

admin_lte:
    routes:
        adminlte_password_reset: ~

Timesheets (kimai.yaml)

Limit active entries

To limit the amount of active entries each user can have, the configuration active_entries can be changed:

kimai:
    timesheet:
        active_entries:
            soft_limit: 1
            hard_limit: 3

The soft_limit is used as theme setting (formerly "kimai.theme.active_warning") to display a warning if the user has at least X active recordings.

The hard_limit is used to detect how many active records are allowed per user (by default 3 active time-records are allowed). If hard_limit is 1, the active record is automatically stopped when a new one is started. When hard_limit is greater than 1 and as soon as the limit is reached, the user has to manually stop at least one active entry (an error message is shown, indicating why it is not possible to start another one).

Descriptions with Markdown

The description for every timesheet entry can be formatted in two different ways, configured with the markdown_content setting.

• false - simple newlines in the description box will be displayed in the frontend as well (default)
• true - description will be rendered with a markdown engine, supporting simple lists and other HTML content

Allowing Markdown in timesheet descriptions is beautiful, but also could be a security risk. Kimai will only apply the markdown in the user timesheet and not in the admin section as additional security measure.

Duration only

Kimai supports two modes for displaying and recording timesheet entries:

• begin and end time (default)
• date and duration (the so called duration_only mode)

When activating the duration_only mode all timesheet tables will only display the date and duration of all records. In addition, the "edit timesheet" forms will be changed and instead of displaying the end date you will see a field for duration. The start date is only visible in these forms when editing an active or starting a new record.

You can activate the duration_only mode by switching the configuration key kimai.timesheet.duration_only to true in the file kimai.yaml.

For supported formats while entering the duration please see the timesheet chapter

Rounding of begin, end and duration for timesheet records

Rounding rules are used to round the begin & end dates and the duration for timesheet records.

1. You can define as many rules as you want ("default" is only an example)
2. Every matching rule will be applied, so be careful with overlapping rules
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
4. If you set one of "begin", "end", "duration" to 0 no rounding will be applied for that field and the exact time (including seconds) is used for calculation
5. The values of the rules are minutes (not the minute of an hour), so 5 for "begin" means we round down to the previous multiple of five
6. You can define different rules for different days of the week
7. "begin" will always be rounded to the floor (down) and "end" & "duration" to the ceiling (up)
8. Rounding rules will be applied on stopped timesheet records only, so you might see an un-rounded value for the start time and duration until you stop the record

You can configure your rounding rules by changing the configuration file kimai.yaml.

Examples

A simple example to always charge at least 1 hour for weekend work (even if you only worked for 5 minutes) could look like this:

kimai:
    timesheet:
        rounding:
            weekend:
                days: ['saturday','sunday']
                begin: 1
                end: 1
                duration: 60

A rule which is often used is to round up to a mulitple of 10:

kimai:
    timesheet:
        rounding:
            workdays:
                days: ['monday','tuesday','wednesday','thursday','friday','saturday','sunday']
                begin: 10
                end: 10
                duration: 0

Hourly rates for timesheet records

If you want to apply different hourly rates multiplication factor for specific weekdays, you can use this rates configuration.

1. You can define as many rules as you want ("workdays" and "weekend" are only examples)
2. Every matching rule will be applied, so be careful with overlapping rules
3. The end_date of timesheet records will be used to match the day (think about entries which are recorded overnight)
4. "days" is an array of weekdays, where the days need to be written in english and in lowercase
5. "factor" will be used as multiplier for the applied hourly rate
6. Rate rules will be applied on stopped timesheet records only, as it can't be calculated before
7. There is no default rule active, by default the users hourly-rate is used for calculation

You can configure the hourly_rate rules by changing the configuration file kimai.yaml.

Examples

1. The "workdays" rule will use the default "hourly rate" for each timesheet entry recorded between "monday" to "friday" as a multiplication with 1 will not change the result
2. The "weekend" rule will add 50% to each timesheet entry that will be recorded on "saturdays" or "sundays"

kimai:
    timesheet:
        rates:
            workdays:
                days: ['monday','tuesday','wednesday','thursday','friday']
                factor: 1
            weekend:
                days: ['saturday','sunday']
                factor: 1.5

Forms (kimai.yaml)

You can set some defaults for various forms within Kimai, to easify the creation process.

Customer creation

Define the default values for a customer like this:

kimai:
    defaults:
        customer:
            timezone: Europe/London
            country: GB
            currency: GBP