Documentation

Backups and restore

Under Administration → Backup you create and manage backups.

What is included?

• MySQL/MariaDB database
• Blob storage (attachments and message bodies)
• Server settings (optional)
• DKIM keys (optional)

What is not included

• The full-text search index. It is derived data and has to be rebuilt after a restore — see step 4 below. Without that step the search finds nothing even though all the data is there.
• The TLS certificate. On a new machine the server obtains a fresh one as soon as DNS points at it.

Restoring through the web interface

1. Upload the backup archive.
2. Choose the restore target (complete or selective).
3. The server restarts afterwards if that is necessary.

Restoring from the command line

This is the path for the real emergency. The web interface stops answering exactly when you need it most — broken database, half-deployed version, deleted directory.

The command works without a running server and refuses while one still answers. That is deliberate: while the dump is being loaded, a running service keeps working on the same tables, and the result is a mixture of two states that only shows up days later.

# List the available archives
sudo annexgroup restore-backup --list

# Stop the service
sudo systemctl stop annexgroup

# Restore
sudo annexgroup restore-backup annexgroup-backup-20260831-090000.tar.gz

Moving to a different machine

The most common reason for a restore is not a disaster but a move: the old machine is going away. The procedure is the same, with four additions.

1. Create an empty database on the new machine, with the same character set:

CREATE DATABASE annexgroup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'annexgroup'@'localhost' IDENTIFIED BY '<password>';
GRANT ALL PRIVILEGES ON annexgroup.* TO 'annexgroup'@'localhost';

2. Transfer the archive and the configuration. The archive belongs in the backup directory of the new installation (<data directory>/backups). Check data_dir and database_dsn in the configuration — otherwise they point at directories that do not exist on the new machine.

3. Restore as above, with the service stopped.

4. Rebuild the search index — with the service still stopped:

sudo annexgroup reindex-search
sudo systemctl start annexgroup

In that order, not the other way round. The search index takes exactly one writer. If the service is already running it holds the lock, and reindex-search aborts with a message saying so.

Then count, do not hope. A restore is only proven once you have compared both sides: sign in over IMAP and over the web interface, open a message with an attachment, and search once for a word you know is there.

Note: Test your backups regularly in a separate environment. A backup that has never been restored is an assumption, not a safeguard.