YunoHost Backups: How the Built-In Archive System Works and How to Run It Safely

YunoHost ships with its own backup system that archives your apps, their databases, and system configuration into compressed tarballs you can restore with a single command. The useful takeaway up front: the built-in tool is reliable for full-server recovery, but it is not incremental, it does not manage disk space for you, and a backup you have never restored is a hope, not a plan. This guide explains how the mechanism works, shows a concrete daily-backup setup, and covers the limits that bite people in practice.

What a YunoHost backup actually contains

When you run a backup, YunoHost does not simply copy the filesystem. Each installed app ships with backup and restore scripts (part of the app package), and the backup tool calls each app's script in turn, alongside scripts for the system parts: user accounts, the LDAP directory, mail configuration, NGINX and DNS settings, and so on. The result is a set of compressed tar archives plus a JSON metadata file, stored by default in /home/yunohost.backup/archives/.

This design has an important consequence: an app is only as restorable as its packaging scripts. Well-maintained official apps support backup and restore fully; a broken or unmaintained app may back up incompletely or fail to restore cleanly. The admin interface shows per-app backup status, which is worth checking after installing anything new.

Creating and inspecting a backup

Run these commands on the YunoHost server itself, as root (or via sudo). The examples assume YunoHost 11.x/12.x; older releases have similar commands but check yunohost backup --help on your version.

# Full backup: system parts plus all apps
sudo yunohost backup create

# System configuration only (small, fast)
sudo yunohost backup create --system

# Only specific apps
sudo yunohost backup create --apps wordpress nextcloud

# List existing archives with timestamps
sudo yunohost backup list

# Show what an archive contains and its size
sudo yunohost backup info 20261013-030000 --with-details

The archive name is a timestamp by default; substitute your actual archive name in the info command. After a backup finishes, verify it before trusting it: check that the archive appears in the list with a plausible size, and confirm free space remains on the disk. A backup that silently stopped at 2 a.m. because the disk filled is a common failure mode.

Scheduling a daily backup with retention

The web admin (under Backup) can create archives, but scheduling is typically done with a cron job. YunoHost also provides a helper, yunohost tools backup is not the mechanism here — the straightforward approach is cron calling yunohost backup create. Create /etc/cron.d/yunohost-backup as root:

# /etc/cron.d/yunohost-backup
# Daily backup at 03:00, then delete archives older than 14 days
0 3 * * * root yunohost backup create >> /var/log/yunohost-backup-cron.log 2>&1
30 3 * * * root find /home/yunohost.backup/archives -name '*.tar*' -mtime +14 -delete

The second line is the retention policy — the part most people forget. Without it, every daily run adds another full archive until the disk fills and the next backup (or worse, an app) fails. Adjust -mtime +14 to however many days of history your disk can hold. A rough sizing rule: one full archive is roughly the compressed size of all your app data and databases, so check du -sh /home/yunohost.backup/archives after the first run and multiply by your retention days.

Check the cron log the morning after the first scheduled run to confirm it executed, and confirm a new timestamped archive exists.

Restoring, and its hard limits

Restore works per archive, either wholesale or per app:

# Restore everything from an archive (destructive to current state)
sudo yunohost backup restore 20261013-030000

# Restore only one app
sudo yunohost backup restore 20261013-030000 --apps wordpress

Per-app restore is the more useful day-to-day operation: you can recover one broken app without touching the rest. The limits to understand before you rely on this:

• No incrementals. Every backup is a full copy of the selected parts. Large apps (a Nextcloud with hundreds of gigabytes of user files) make archives slow and huge. For very large data directories, consider excluding that data from the YunoHost backup and handling it with a dedicated tool like Borg or restic.
• Local archives are not a disaster plan. Backups in /home/yunohost.backup/archives die with the server. Copy them off-machine — rsync, scp, or an object-storage sync — as part of the same cron window.
• Restore overwrites. Restoring an app replaces its current data. There is no merge. Test restores on a spare VM or a snapshot before you need one for real.
• Version drift. Restoring an archive onto a much newer YunoHost or app version can fail if the app's restore script has changed. Keep the server reasonably up to date so archives stay restorable.

Common mistakes

• No retention policy, leading to a full disk weeks later. Fix: the find ... -delete cron line above, or a small pruning script.
• Ignoring database size. A database dump must be written to disk during backup, temporarily doubling its footprint. Check df -h headroom before the first full run.
• Never testing a restore. Schedule one test restore per quarter on a VM; it is the only way to know the archive and the app restore scripts actually work.
• Backing up during heavy write activity. Backups are not atomic snapshots; a database written mid-backup can be inconsistent. Run backups at quiet hours, which the 03:00 schedule above assumes.

Verifying the whole setup

After configuring, verify in order: (1) yunohost backup list shows a fresh archive after each scheduled window; (2) yunohost backup info <name> reports the expected apps and a sane size; (3) the off-server copy exists on the remote side; (4) a test restore of one non-critical app succeeds on a spare machine. If all four pass, you have a backup system rather than a backup ritual.