Skip to main content

How to Backup

Introduction​

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.

Did you backup?

There are 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)

How to backup a Docker installation​

Important note​

The instructions below are merely a suggestion on how to proceed. If you are familiar with different tools or procedures to backup data, use them. At the end of the day, eLabFTW's data is a very classical MySQL database and even more classical files. The important points are:

With elabctl​

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.

Configuration​

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

Automate backups​

Content of /etc/systemd/system/elabftw-backup.service:

[Unit]
Description=Backup eLabFTW data

[Service]
Type=oneshot
ExecStart=/path/to/elabctl backup
# Make sure to use a user with enough rights
User=root

[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:

  • MySQL dump
  • Uploaded files
  • Configuration file

To extract your uploaded files from a borg backup:

export BORG_REPO=/path/to/borg/repo
export BORG_PASSPHRASE="your passphrase"
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 :)