Backups

Backup

You have to backup the following files:

  • .env
  • config/packages/local.yaml
  • the directory var/data/

The following stuff needs attention as well, backup if necessary:

  • all customized files
  • all added invoice templates
  • installed plugins at var/plugins/

Database:

  • All tables starting with kimai2_
  • The table migration_versions
  • Best is to backup all tables in the database with all data!

Write down the exact version of your Kimai installation:

  • bin/console kimai:version
  • git rev-parse HEAD

Create a database backup

Here is a one liner that creates a database backup for MySQL/MariaDB (adjust connection to your needs):

mysqldump --single-transaction -u kimai2 -p -h 127.0.0.1 kimai2 > ~/kimai2-`date +%F_%H-%M`.sql

Or with SQLite

cp var/data/kimai.sqlite ~/kimai2-`date +%F_%H-%M`.sqllite

Restore

  • install Kimai as documented in the exact same version, which you used when you created the backup
  • make sure it works
  • restore the database backup in an empty database
  • point .env to your imported database

Now refresh your cache:

How to reload Kimai cache

bin/console kimai:reload --env=prod

FTP users: please have a look at this documentation.

If you are running an older version of Kimai (before 1.8) you have to use:

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

At this step: test Kimai again and don’t proceed before it works as expected!

Working properly? If not, check your file permissions:

Fix Kimai file permission

You have to allow PHP (your webserver process) to write to var/ and it subdirectories.

Here is an example for Debian/Ubuntu (to be executed inside the Kimai directory):

chown -R :www-data .
chmod -R g+r .
chmod -R g+rw var/
chmod -R g+rw public/avatars/

Test Kimai before executing these commands (they are likely not required in a shared-hosting environment). You probably need to prefix them with sudo and the group might be called different than www-data.

Working now? Fine, then go ahead and restore all other files:

  • invoice templates
  • plugins
  • local.yaml

Still not satisfied and want to upgrade to the latest version?

Great! Make sure you have the migration_versions table in your database backup, before you upgrade. If not, execute bin/console doctrine:migrations:version --add --all beforehand and read the installation docs again, if you might have missed other points as well.

Now you can upgrade :-)

Pitfall version change

You restored Kimai (as documented above), but have problems when accessing it?

Maybe you have missed an upgrade steps, which you would have done when executing a normal upgrade.

Please check the UPGRADING guide and make sure you executed all version specific tasks.

Database

If Kimai will not load properly (e.g. you only see a white screen, maybe some pages work) the database could be the reason. This problem can happen when you install a different (newer) version that has a different database structure then your backup.

Check your database if you have the migration_versions table. If not, go back to “Restore”. If so: try to execute the missing database migrations with bin/console kimai:update -n.

Configuration

You see an error when executing bin/console cache:clear.

This problem can happen when a configuration change is necessary in your local.yaml. Please check the UPGRADING guide.

Backup script

The following solution is a very simple, but working way to backup your Kimai installation. It will store the database, your environment file, the installed plugins and generated data (eg. invoice files).

I recommend to create a dedicated user on the server that will store the backups:

useradd -m -s /bin/bash backup

Create a MySQL configuration file to store the connection password for the Kimai database user at /home/backup/.kimai2.cnf:

[client]
password=my-super-password

Make sure it can only be read by that user:

chmod 600 /home/backup/.kimai2.cnf

Create the backup script at /home/backup/backup.sh and adapt to your needs:

#!/bin/bash

export CONNECTION_CONFIG=/home/backup/.kimai2.cnf
export KIMAI_DIR=/var/www/kimai2
export BACKUP_DIR=/home/backup

export DATE=`date +%F_%H-%M`
export BACKUP_STORAGE_DIR=$BACKUP_DIR/storage
export BACKUP_TMP_DIR=$BACKUP_DIR/temp/$DATE

mkdir -p $BACKUP_STORAGE_DIR
mkdir -p $BACKUP_TMP_DIR
mkdir -p $BACKUP_TMP_DIR/var/data/
mkdir -p $BACKUP_TMP_DIR/var/plugins/

mysqldump --defaults-file=$CONNECTION_CONFIG --single-transaction --no-tablespaces -u kimai2 -h 127.0.0.1 kimai2 > $BACKUP_TMP_DIR/kimai2-$DATE.sql

cp $KIMAI_DIR/.env $BACKUP_TMP_DIR/
cp -R $KIMAI_DIR/var/data/* $BACKUP_TMP_DIR/var/data/
cp -R $KIMAI_DIR/var/plugins/* $BACKUP_TMP_DIR/var/plugins/

pushd $BACKUP_TMP_DIR
zip -r $BACKUP_STORAGE_DIR/$DATE.zip * .env
popd

Now edit the servers crontab with crontab -e and add the following lines:

10 1 * * * /home/backup/backup.sh >> /var/log/kimai-backup.log 2>&1
20 2 * * * find /home/backup/storage/* -atime +60 -type f -delete