Backups and updates

These commands assume the application checkout and compose.yaml from Install Middlewarr. Run them from that checkout.

Back up the data directory

Stop Middlewarr before copying the data so SQLite and the other files are not changing during the backup:

docker compose stop middlewarr
tar -czf "middlewarr-data-$(date +%Y%m%d-%H%M%S).tar.gz" data
docker compose start middlewarr

Check that the archive command succeeded before relying on the backup. Store a copy separately from the host, with access restricted because it contains credentials and session data.

Back up the Compose file and record the application source revision too:

git rev-parse HEAD

Do not put data archives into the application’s Git repository. Periodically test a restore in an isolated environment before you need it for recovery.

Restore a backup

1. Stop Middlewarr.
2. Preserve the current data directory elsewhere if you may need to return to it.
3. Extract the archive so the restored data/ directory is beside compose.yaml. Do not merge it with a partially populated database directory.
4. Start a container built from the source revision recorded with the backup.
5. Check startup logs, sign in, and test one allowed request through a proxy.

The backup includes the administrator and sessions that existed when it was taken. If you cannot sign in, follow administrator recovery.

Template sources sync at startup, so a restored installation can receive newer template changes. Review the resulting permissions. For repeatable template contents, maintain a branch you control.

Update the application

Back up first and check the release or source changes you intend to use. For a checkout that tracks a branch and has no local changes:

git pull --ff-only
docker compose build --pull middlewarr
docker compose up -d middlewarr
docker compose logs --tail=100 middlewarr

If you use a chosen tag or commit, check out that revision instead of pulling a branch. Keep your previous revision and backup together.

After updating, confirm sign-in, a service’s connectivity, an allowed proxy request, and a blocked request. Check template sync results and recent permission changes.

SQLite schema changes are applied at startup. Do not assume an older application can read a database modified by a newer build. For rollback, restore the matching backup and previous application revision together.

Routine checks

Review unresolved access warnings, template sync errors, unexpected permission changes, disk usage under /data, and notification test results. Recreate containers freely as long as the persistent mount is preserved.

The bundled container does not include a shell or curl. Probe /health from the host or a separate monitoring client instead of assuming a shell-based health check can run inside it.