How to Create, Verify, and Restore a YunoHost Server Backup

If your YunoHost server dies tomorrow, the question is not whether you have backups, but whether you have ever restored one. YunoHost's integrated backup system packages installed applications, user accounts, and system configuration into a single compressed archive, but that archive is only useful if it lives outside the failing disk and has been tested against a clean installation.

This guide walks through creating a server-wide backup, moving it to external storage, and validating the restore path on a fresh YunoHost instance.

What the backup archive contains

YunoHost does not create a raw disk image. Instead, its backup subsystem exports the state of the system: application files, application databases, user accounts and permissions, and core system configuration. Because everything is bundled through one interface, you do not need to manually dump databases or copy application directories before running the backup.

Prerequisites

• SSH access with root privileges. YunoHost administration commands require root. Log in as root or use a user with sudo rights.
• Free disk space. Backups are written to /home/yunohost.backup by default. Check available space with df -h /home before starting.
• A clean target machine. To validate the backup, you need a second YunoHost installation running the same major version as the source.
• Off-server storage. An external NAS, object storage bucket, or another server reachable by SSH.

Create the backup archive

You can trigger a backup from the web admin panel, but the command line gives you scriptable control. Run the following on your YunoHost server over SSH as root:

yunohost backup create

YunoHost will compress the selected components into an archive inside /home/yunohost.backup/. On large installations, expect noticeable I/O load and disk consumption while the compression phase runs. If your server is under memory or CPU pressure, schedule the backup during a maintenance window.

Expected check: list the backup directory to confirm a new archive appeared:

ls -lh /home/yunohost.backup/

You should see a new .tar.gz file with a size proportional to your installed data. If the directory is empty or the command returned an error, check system logs and available disk space before retrying.

Move the archive off the server

A backup stored on the same disk as the live system does not protect against hardware failure. Copy the archive to external storage immediately after creation. The following example uses rsync over SSH; replace the placeholders with your actual backup host and destination path:

rsync -avz /home/yunohost.backup/ user@backup-host:/srv/yunohost-backups/

Run this from your YunoHost server (or from the backup host, pulling instead of pushing). Verify the file size on the destination matches the source.

Test the restore on a clean instance

An untested backup is a hypothesis. On a freshly installed YunoHost server running the same version as the source, restore the archive. If the file is not in the default backup directory, provide the full path; otherwise reference it by name:

yunohost backup restore /path/to/your-archive.tar.gz

The restore process re-creates user accounts, re-installs application data, and re-applies system configuration. Depending on the size of the archive, this may take several minutes.

Expected checks after restore:

• Log in to the web admin panel at https://your-domain/yunohost/admin.
• Confirm that previously installed applications are listed and respond.
• Check that user accounts and their permissions match the source server.
• Verify core services (NGINX, DNS, firewall) are active.

Recovery options when the restore fails

Version mismatch errors

Restoring a backup onto a different YunoHost version can trigger dependency conflicts or configuration errors. If the clean instance is newer or older than the source, restore onto a matching version first, then use YunoHost's upgrade tools to move forward.

Disk space exhaustion during backup

If yunohost backup create fails because the disk is full, remove obsolete archives from /home/yunohost.backup/ or mount an external volume with sufficient space and direct backups there.

Partial application failure

If a specific application does not work after a system-wide restore, check that application's logs through the YunoHost admin panel or under /var/log/. In some cases, re-installing the affected app and restoring only its data may be faster than debugging a broken system state.

Limitations to plan around

The backup system captures YunoHost-managed state, not arbitrary low-level system modifications. If you have installed custom packages outside the app system or edited configuration files directly, those changes may not be included. Treat the YunoHost backup as one layer of a broader disaster-recovery plan.

Also, because the archive is a structured export rather than a bootable image, you cannot simply mount it to recover individual files without using YunoHost's restore tooling. Keep a separate file-level backup if you need granular recovery outside the YunoHost ecosystem.

Finally, exact command flags and default paths can vary between YunoHost releases. Run yunohost backup --help on your server to confirm the syntax for your installed version before relying on it in production.