Backing Up and Restoring a Yunohost Server: A Practical Task Guide

The Problem: A Backup You Cannot Restore

Many self-hosted Yunohost servers run a background backup job, but the archive has never been restored. When a disk fails or an app upgrade corrupts data, the operator discovers too late that the archive is incomplete, encrypted with a lost passphrase, or created by an incompatible Yunohost version. This guide produces a backup that is created, verified, and actually restorable.

Desired Outcome

A consistent, restorable snapshot of the Yunohost system configuration, installed applications, user accounts, home directories, and mail data. The archive should be created on demand or on a schedule and later restored to the same server or a fresh Yunohost instance without manually reconstructing files.

Prerequisites

• Root or sudo access to the Yunohost host, because backup and restore operations read and write system paths and service configurations.
• Sufficient free disk space on the destination filesystem for the full archive plus temporary working space. Mailboxes and media-heavy apps can make archives large.
• A defined backup destination, such as a local directory on a separate disk or a mounted remote share. Avoid storing the only copy on the same physical drive as the live system.
• Awareness of app-specific limitations. Some applications store data outside Yunohost-managed paths or require manual steps after a restore; these will not be fully captured by the standard backup.

Creating the Backup

Yunohost includes an integrated backup command that collects system settings, apps, home directories, and mail data into a timestamped archive. Run it from a shell on the Yunohost server.

sudo yunohost backup create

By default this creates a full system archive. To limit the backup to specific applications, pass their names as arguments. For example, to back up only a Nextcloud instance and the system configuration:

sudo yunohost backup create nextcloud --system

Replace nextcloud with the actual app name shown in the web admin. The --system flag includes Yunohost system settings, user accounts, and domain configuration; check the documentation for your Yunohost version because flag behavior can change between major releases.

You can also protect the archive with encryption. When prompted, supply a passphrase. Store this passphrase offline in a password manager or on paper, separate from the backup files. If the passphrase is lost, the archive is unrecoverable.

For scheduled backups, the Yunohost web administration interface exposes a backup section where you can configure automatic archives and retention. Alternatively, wrap the CLI command in a cron job or systemd timer, ensuring the destination has enough space and that old archives are pruned according to your retention policy.

Verifying the Archive

After the command completes, confirm the archive exists and is non-trivial in size. List the backup directory:

ls -lh /var/lib/yunohost/backups/

Replace the path with your configured backup directory if you specified a custom output location. Look for a recent timestamped archive.

Next, inspect the archive metadata using the Yunohost CLI:

sudo yunohost backup list

This shows available archives. To see what a specific archive contains, run:

sudo yunohost backup info <archive-name>.tar.gz

Replace <archive-name>.tar.gz with the exact filename from the list. Confirm that the manifest includes the expected apps and user accounts. Check system logs for backup job completion messages and the absence of error entries.

Recovery Options

Full System Restore

To recover the entire server, use the Yunohost restore workflow. On current Yunohost releases this is typically initiated during the post-installation process on a fresh server or through the web admin interface; the exact command-line entry point varies by version, so verify the procedure for your release before an emergency. The workflow stops running services through pre-restore hooks to avoid data corruption, then unpacks the archive and reapplies system settings, apps, and user data.

Selective App Restore

If only one application is broken, you can restore that app alone from an archive rather than the whole system. This is useful when a plugin or app upgrade fails but the underlying Yunohost configuration remains intact.

Restoring to a Different Host

Archives can be restored to a different machine, but the target host must have aligned domain names and IP addresses. If the public IP or DNS records have changed, update them before restoring so that mail and web services function correctly afterward.

Recovery if Restore Fails

Because restore modifies system state, plan a recovery path. If a restore fails partway, the safest option is to reinstall Yunohost on the target host and retry the restore from the same archive. Keeping multiple timestamped archives lets you fall back to an earlier snapshot if the most recent one is corrupted.

Limitations and Risks

• Version skew: Backup formats and included components evolve across Yunohost major releases. An archive created on an older release may require an intermediate upgrade path before it can be restored on a newer version.
• External data: Application data stored outside Yunohost-managed paths is not captured by the standard backup. Review each app's documentation for additional export steps.
• Archive size and I/O: Large mail and media collections can exhaust destination space or cause partial archives if the filesystem is slow or full. Monitor free space before and during backup.
• Service conflicts: Restoring over a running system can cause conflicts. Stop relevant apps or perform the restore from a fresh installation when possible.

Practical Verification

Do not assume an archive is good because the command exited successfully. Create a small test backup on a non-production instance, inspect the archive listing for expected app folders and configuration files, and perform a dry-run restore of a single non-critical app. After restore, log in to the web admin panel and confirm that apps show as installed and user accounts are present. Test access to the restored app's data to verify that files and database content reloaded correctly. Only after this rehearsal should you rely on the backup for disaster recovery.