Backups and upgrades

Take a backup

Open More → System → Data and recovery, then choose Back up now. Aldus creates and verifies the archive on the server. Download a copy from the same page and keep it somewhere outside the Aldus host.

The command line remains available when the web application cannot start:

docker compose run --rm aldus backup \
  --archive /backups/aldus-backup-$(date +%Y%m%d).tar.gz

This runs against the live server — Aldus does not need to be stopped. Use the same release as the running server. If Aldus reports that the database belongs to a different release, run the backup with the matching release; the backup command does not upgrade your database. --archive must point somewhere outside the data directory itself (/backups is the dedicated backup volume in the default Compose setup); Aldus refuses to write a backup inside the directory it’s backing up, and refuses to overwrite a file that already exists at the target path.

What actually happens during a backup

A true hot snapshot

Aldus reads the live database without changing it and makes a consistent copy using SQLite, the software that stores your library records. You can keep using the server during the backup.

Dedicated credentials and sessions are removed

In the backup copy, Aldus removes saved provider and download-client credentials, including Prowlarr, qBittorrent, SABnzbd, and the New York Times API key. It also removes active app sessions and saved download links. The running server keeps its credentials and sessions.

Every file is checksummed

Aldus records a checksum — a value used to detect changes — for each file. Before reporting success, it reads the completed archive and checks every file against that record. It extracts only the database for additional checks, without making a second full copy of your media.

Included and excluded

The archive contains the redacted database snapshot plus managed acquisition downloads, covers, and alignment artifacts. Reproducible alignment model caches are excluded and repopulate automatically after restore. It does not contain the files behind your external Sources — those live in a folder you own outside Aldus’s data directory, so only their catalog metadata (title, author, path, checksum) travels in the database snapshot, not the file bytes themselves. In practice this means a backup restores your library’s structure, progress, requests, and anything Aldus downloaded on your behalf — but you’re still responsible for backing up the actual media folder you pointed ALDUS_SOURCE_PATH at, separately, with whatever tool you already use for that.

Aldus also refuses to include a symbolic link anywhere under the data directory, and the restore path rejects any archive entry that isn’t a plain file or that tries to write outside the target directory — both are hard failures, not warnings.

Restore

Run these commands in your Aldus folder on the server, beside compose.yml and .env. They use a downloaded backup, so they also work when the original server or backup volume is gone. If you normally use a custom Compose project name or extra -f files, include those same options in every command below.

Use the release that created the backup, or a newer compatible release. For a rollback, use the backup taken before the upgrade and its original release. Do not start an older image against data already upgraded by a newer release.

Prepare the files

Place your downloaded archive in a folder named restore-files beside compose.yml. In the commands below, replace aldus-backup.tar.gz with its filename.
Keep your .env and any customized Compose files with your backups. They are not included in the archive. You will need the same settings, especially your media folders and network address.
Restore external book and audiobook folders from their separate backups. Set ALDUS_SOURCE_PATH in .env to their location on this host. Keep the same folder structure and paths inside the container so Aldus can find the cataloged files. Restore any additional custom media mounts too.

On the same host

These steps apply to the standard Compose setup, which stores /data in a named Docker volume.

Stop Aldus and identify its actual data volume before removing the container:
Terminal window
```
docker compose stop aldus
ALDUS_CONTAINER=$(docker compose ps --all --quiet aldus)
docker inspect "$ALDUS_CONTAINER" --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Type}} {{.Name}} {{.Source}}{{end}}{{end}}'
```
If the command fails or prints no mount, stop and check that you are using the right Aldus folder and Compose options. The output must begin with volume, followed by its name, such as aldus_aldus-data. Use the name shown on your server; the folder used to install Aldus affects this name. Write down this name so you can identify the original data later. If the output starts with bind, you use a custom host folder: move that folder to a safe location and create an empty replacement at the same path, with the same ownership and permissions. Skip the named-volume change below.
Keep the old data while you restore into a new, empty volume. First save a copy of your Compose file:
Terminal window
```
cp compose.yml compose.before-restore.yml
```
In compose.yml, add name under the existing aldus-data entry at the bottom. Leave aldus-backups and all other settings unchanged:
```
volumes:
  aldus-data:
    name: aldus-restored-20260909
  aldus-backups:
```
Choose a new name for each restore. Check it with docker volume inspect aldus-restored-20260909: no such volume means the name is available. If a volume already exists, choose another name. Keep this setting in your Compose file after restoration; removing it would switch Aldus back to the old data.
Remove only the stopped container:
Terminal window
```
docker compose rm --force aldus
```
Your original data and backup volumes remain on disk. Do not run docker compose down --volumes or delete either volume. The restored library will contain the backup’s accounts, progress, and files; changes made after that backup stay only in the original data. Keep that original volume until you have checked the restored library. Allow enough free disk space for both copies.

On a new host

Install Docker and its Compose plugin as described in Install. Create an Aldus folder and copy in your saved .env, Compose files, and restore-files folder. If you did not save the configuration, download the Compose files from the release that created the backup and recreate your settings using the install guide.
Restore and configure the external media folders as described above. Pull the selected image with docker compose pull, but do not start Aldus yet. Starting it creates a database; restore requires an empty data volume. If you already started it, follow the same-host steps before continuing.

Restore and check

Restore from the downloaded archive:
Terminal window
```
docker compose run --rm \
  --volume "$PWD/restore-files:/restore-input:ro" \
  aldus restore --archive /restore-input/aldus-backup.tar.gz --data-dir /data
```
Compose creates the empty data volume if needed. Aldus checks the archive and refuses a damaged backup, an unsupported database version, or a nonempty destination. Wait for the command to finish successfully before starting the server. If it fails, keep the archive and resolve the reported error first.
Start Aldus and check its status:
Terminal window
```
docker compose up -d
docker compose ps
```
For NVIDIA installations, use the matching GPU command under Upgrading below when starting the server. Wait until Aldus reports healthy. If it does not, run docker compose logs --tail=100 aldus.
Sign in again on each app or browser. Open a book, play an audiobook if available, and check that a saved reading position from the backup returns. If externally stored books are unavailable, check their restored folders and mounts.
Reconnect your configured providers and download clients, including Prowlarr, qBittorrent, or SABnzbd under Acquisitions → Connections. Re-enter your New York Times API key if used. Saved sessions and these credentials are deliberately excluded from backups.

Upgrading

Run these steps in your existing Aldus folder. Keep your current .env values, media paths, and Compose customizations.

Create and download a verified backup. Save copies of .env, compose.yml, and any GPU or custom override files outside this folder so you can restore the previous configuration.
Download the new release’s Compose file under a temporary name. Replace 0.1.0-beta.22 with your target release:
Terminal window
```
ALDUS_TARGET_VERSION=0.1.0-beta.22
curl -fL "https://github.com/Mahcks/Aldus/releases/download/v$ALDUS_TARGET_VERSION/compose.yml" -o compose.release.yml
```
Compare compose.release.yml with your existing compose.yml. Apply the release’s changes while keeping your custom mounts and settings. If your existing file is unchanged from the previous release, you can replace it with the downloaded file.
Edit only the ALDUS_VERSION line in your existing .env to the target version. Do not replace the whole file: that would discard your other settings. Keep the version without a GPU suffix; the GPU override selects that image.
Choose the command for your installation:

CPU:
Terminal window
```
docker compose pull
docker compose up -d
```
NVIDIA CUDA (Turing and newer, including GTX 16-series and RTX cards):

Download and review the matching override, preserving any custom settings before replacing your existing file:
Terminal window
```
curl -fL "https://github.com/Mahcks/Aldus/releases/download/v$ALDUS_TARGET_VERSION/compose.gpu.yml" -o compose.gpu.release.yml
```
Once the reviewed file is saved as compose.gpu.yml, run:
Terminal window
```
docker compose -f compose.yml -f compose.gpu.yml pull
docker compose -f compose.yml -f compose.gpu.yml up -d
```
NVIDIA CUDA legacy (Maxwell, Pascal, or Volta, including GTX 900/10-series):

Use this option only if the target release includes compose.gpu-legacy.yml. Otherwise, use CPU processing; see GPU support.
Terminal window
```
curl -fL "https://github.com/Mahcks/Aldus/releases/download/v$ALDUS_TARGET_VERSION/compose.gpu-legacy.yml" -o compose.gpu-legacy.release.yml
```
Review it and preserve your custom settings. Once saved as compose.gpu-legacy.yml, run:
Terminal window
```
docker compose -f compose.yml -f compose.gpu-legacy.yml pull
docker compose -f compose.yml -f compose.gpu-legacy.yml up -d
```
Use only one GPU override. If you normally supply other custom -f files, keep including them in your Compose commands.
Run docker compose ps and wait for healthy. Open Aldus and confirm you can read a book and resume your saved place. If startup fails, check docker compose logs --tail=100 aldus.

If you need to roll back, restore the pre-upgrade backup using the procedure above and the saved previous .env and Compose files. Avoid latest for a server you depend on — see Install for why.

A realistic schedule

A single backup taken right before an upgrade protects you from that upgrade. It doesn’t protect you from a bad disk, an accidental library deletion, or three months of drift you didn’t notice. A reasonable baseline for a household server:

Before every upgrade or config change, always — this is the one that actually saves you most often.
Nightly, via a host cron job calling the same docker compose run --rm aldus backup command with a dated filename, kept for a couple of weeks.
Weekly, copied off the host entirely — onto separate storage, or synced to cloud storage — so a lost or failed host doesn’t take the backups with it.

Because backups are hot and checksummed automatically, there’s little cost to running them more often than feels necessary.