YunoHost Backups: One Archive, One Restore – A Practical Guide

Why a Unified Backup Matters for Self‑Hosters

When you run a self‑hosted stack, you usually have dozens of services: mail, web, media, databases. Losing a single file can break an entire app, yet restoring each component individually is error‑prone. YunoHost solves this by shipping a single yunohost backup create command that bundles an app’s data, configuration, and database into one tar archive. The same archive can be used to restore the app on a fresh YunoHost install, making it a reliable migration path.

How the Backup Pipeline Works

Every YunoHost app declares two scripts in its Debian package:

• app/backup – gathers the files, configuration and database dumps.
• app/restore – extracts and re‑installs them.

When you run yunohost backup create --apps wordpress, the core calls the WordPress backup script, which typically:

1. Stops the web service to avoid a half‑written database.
2. Runs mysqldump for the WordPress database.
3. Copies the wp-content directory.
4. Creates a tar archive in /home/yunohost.backup/archives.

The archive is a standard tar.gz file, so you can move it with rsync, scp, or store it in a backup tool like Borg or Restic for deduplication and encryption.

Example: Backing Up and Restoring WordPress

# On the source server
sudo yunohost backup create --apps wordpress
# Archive appears at /home/yunohost.backup/archives/wordpress_2026-10-13.tar.gz

# Transfer to a fresh YunoHost instance (replace user@dest by your target host)
sudo rsync -avz /home/yunohost.backup/archives/wordpress_2026-10-13.tar.gz user@dest:/tmp/

# On the destination server
sudo yunohost backup restore /tmp/wordpress_2026-10-13.tar.gz
# The restore script recreates the database, copies wp-content, and re‑enables the service

After the restore, visit https://your-wordpress.example.com to verify that all posts, media, and settings are intact. If the app fails to start, check the logs in /var/log/yunohost/wordpress.log for error hints.

Trade‑Offs & Limitations

• App‑Dependent Quality – The backup’s completeness depends on the maintainer’s scripts. Some apps, like Nextcloud, include large user data directories that can inflate archive size dramatically. If you only need configuration, you can exclude data via --exclude-data.
• Same‑Disk Storage – By default archives live on the same disk as production data. A disk failure can wipe both. Always copy the archives off‑site or to a separate volume.
• Version Compatibility – Restoring across major YunoHost or app version jumps may break dependencies. Test restores on a staging server before applying to production.
• Large App Times – Backing up a Nextcloud instance with 5 TB of user files can take hours. Schedule during off‑peak windows and consider incremental backups with Borg.

Practical Checklist for Robust Backups

1. Verify Backup Scripts – Inspect /usr/share/yunohost/apps/wordpress/backup to confirm what is captured.
2. Test Restore Early – Use a throwaway VM to restore the archive and verify the app runs.
3. Off‑Site Copy – Automate rsync or borg to copy archives to a remote server or cloud bucket.
4. Monitor Archive Size – Set up a cron job that reports archive size and age; alert if it grows beyond a threshold.
5. Document Restore Steps – Keep a short SOP in your ops manual: command, target path, expected log messages.

Conclusion: One Archive, One Decision

YunoHost’s integrated backup system turns a complex, multi‑app environment into a single, consistent snapshot. While the approach is simple, its reliability hinges on each app’s backup scripts and on external off‑site storage. By testing restores, monitoring archive size, and keeping an off‑site copy, you can turn the built‑in backup into a dependable part of your disaster‑recovery plan.