How to backup
This page documents how to backup an existing eLabFTW installation. It is important that you take the time to make sure that your backups are working properly.
There is basically three things to backup :
the MySQL database (by default in /var/elabftw/mysql)
the uploaded files (by default in /var/elabftw/web)
your configuration file (by default /etc/elabftw.yml): not really required if you use provisioning tools like Ansible and store your config/secrets somewhere else
How to backup a Docker installation
Using the backup function of elabctl is the recommended approach. The MySQL database will be dumped thanks to mysqldump present in the mysql container. The uploaded files will be copied with borgbackup and you need to install it first and then configure it.
Start by figuring out where you want the borg repository to live. It can be local or remote folder (remote is better but requires ssh correctly setup to access it). It can also be local but on a network-mounted path, which makes it remote.
After installing borg, initialize a new repository with:
# for a local path borg init -e repokey-blake2 /path/to/elabftw-borg-repo # for a remote (ssh) path borg init -e repokey-blake2 someserver:/path/to/elabftw-borg-repo
It is necessary to use the elabctl.conf configuration file (available here). Place this file in /root/.config/elabctl.conf and make sure to specify the settings correctly.
Try the backup with:
You can also use mysql-backup to only backup the MySQL database:
You can also use borg-backup to only backup the uploaded files:
Important: verify that all the files are correctly created and that you will be able to restore from a backup!
You’re on your own. Use your favorite tools to backup the MySQL database and uploaded files.
Making it automatic using cron
A good backup is automatic. Use a cronjob or a systemd timer job to trigger the backup job regularly (ideally daily).
With a cronjob
If you have the traditional cron service running, try:
This will open the cronjob file in edit mode.
Add this line at the bottom:
00 04 * * * /path/to/elabctl backup
This will run the script everyday at 4am. Make sure to write the full path to elabctl as it might not be in the $PATH for cron.
With a systemd timer
Some systems don’t use the traditional cron service, so instead of installing it, you should use a systemd timer (provided systemd is your init system, which is quite likely).
You will need to create two files, one .service and one .timer.
Content of /etc/systemd/system/elabftw-backup.service:
[Unit] Description=Backup eLabFTW data Wants=elabftw-backup.timer [Service] Type=oneshot # make sure to edit the path below ExecStart=/path/to/elabctl backup [Install] WantedBy=multi-user.target
Content of /etc/systemd/system/elabftw-backup.timer:
[Unit] Description=Backup eLabFTW data [Timer] OnCalendar=*-*-* 4:00:00 Persistent=true [Install] WantedBy=timers.target
Now activate it:
systemctl enable elabftw-backup systemctl start elabftw-backup
How to restore a backup
You should have three files/folders to start with:
A MySQL dump (file ending in .sql or .sql.gz)
Your uploaded files as a borg archive
Possibly your configuration file
To extract your uploaded files from a borg backup:
export BORG_PATH=/path/to/borg/repo borg list borg extract "::example-2022-07-14_13-37"
See documentation on how to manage your borg repository: Borg extract documentation.
Then we move the uploaded files and config file at the correct place (adjust the paths to your case):
mv /path/to/uploaded-files-backup/* /var/elabftw/web mv /path/to/configuration-backup-elabftw.yml /etc/elabftw.yml # now fix the permissions chown -R 101:101 /var/elabftw/web chmod 600 /etc/elabftw.yml
Now we import the SQL database (the mysql container must be running):
gunzip mysql_dump-YYYY-MM-DD.sql.gz # uncompress the file docker cp mysql_dump-YYYY-MM-DD.sql mysql:/ # copy it inside the mysql container docker exec -it mysql bash # spawn a shell in the mysql container mysql -uroot -p$MYSQL_ROOT_PASSWORD # login to mysql prompt Mysql> drop database elabftw; # delete the brand new database Mysql> create database elabftw character set utf8mb4 collate utf8mb4_0900_ai_ci; # create a new one Mysql> use elabftw; # select it Mysql> set names utf8mb4; # make sure you import in utf8 (don't do this if you are in latin1) Mysql> source mysql_dump-YYYY-MM-DD.sql; # import the backup Mysql> exit;
Now you should have your old install back :)