Backup and Restore

Data loss can happen for numerous reasons - hardware failures, accidental deletions, cyberattacks, or even natural disasters. For self-hosted applications like HomeVault that store your important personal data, implementing a robust backup strategy is not just recommended—it's essential.

HomeVault provides a comprehensive backup solution that:

• Creates fully-encrypted backups of your server
• Supports multiple cloud storage providers (Backblaze B2, iDrive e2, Wasabi, AWS S3, and any other provider supported by restic)
• Allows both on-demand and scheduled backups
• Simplifies disaster recovery through a streamlined restore process

The snapshot created during a backup does not have an entire image of your server. Instead, here's what gets backed up:

• App configuration data
• User-generated content
• Database files
• Module configurations
• Any customizations you've made to your HomeVault instance

[!info] The backup operations described below are performed using HomeVault's script: hv. This is the script you downloaded during Server Deployment. You will need to open a remote session to your system using SSH or Termius and change to the directory where your workspace is located, which by default is: ~/homevault/workspace

Initializing the Backup System

Before creating your first backup, you need to initialize the backup system with your cloud storage provider credentials. This is done by using the backup init command of the setup script.

Step 1. Creating the Configuration File

When initializing the backup system you need to provide information about your backup repository. This is, the location where backups will be located (for example, a cloud storage address, a removable hard-drive, etc.). The easiest way to provide this information to the script is to create a restic.env file at the root of your workspace.

To create this file, you can use nano, vim or your favorite terminal-based editor:

nano restic.env

In this file you should include values for RESTIC_REPOSITORY and RESTIC_PASSWORD. Depending on the storage provider you choose to use for your backups, you will also need to include authentication credentials (varies by provider).

[!tip] If you do not include a RESTIC_PASSWORD on your restic.env file, the script will create a new password for you and display it along with the output of the backup init command.

For example, if using AWS S3, your restic.env file would look like the following:

RESTIC_REPOSITORY=s3:s3.<region>amazonaws.com/<your-bucket-name>
RESTIC_PASSWORD=your-secure-encryption-password
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Backblaze B2, iDrive e2, Wasabi, provide S3-compatible API to access your data, and the format of your restic.env would be very similar. For example, to use Backblaze B2, you need to create S3-Compatible App Keys and provide them in your restic.env file:

RESTIC_REPOSITORY=s3:https://s3.<region>.backblazeb2.com/<your-bucket-name>
RESTIC_PASSWORD=your-secure-encryption-password
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Step 2. Running the Script

Once your restic.env file is complete, you can initialize the backup system with the backup init command as follows:

./hv backup init --restic-env restic.env

Step 3. Preserve a copy of your environment file

Once the backup system is initialized, you should keep a copy of the restic.env file stored somewhere safe. You will need this file if you need to restore a backup snapshot later in the future.

[!warn] If you loose your RESTIC_PASSWORD, your backups will be permanently and irreversibly lost. Make sure to keep the copy of your restic.env file contains the RESTIC_PASSWORD that was used to initialize the backup system, and store its contents in a safe place (e.g. using a password manager)

Creating On-Demand Backups

To create a backup of your server immediately, you can use the backup run command. This requires having previously initialized the backup system, as shown in the previous section.

./hv backup run

If you have scheduled automated backups and enabled a retention policy, you can create on-demand backups and mark them for long-term retention, by adding the --keep flag:

./hv backup run --keep

Automated Backups

HomeVault allows you to schedule regular backups to run automatically in the background. By default, regular backups are disabled after the initial server deployment.

[!tip] You need to initialize the backup system before enabling and configuring automated backups.

With the backup schedule command you can:

• Enable and disable the automated backups
• Change the recurrence schedule for the automated backups
• Change or disable the retention policy

Enabling and disabling automated backups

You can enable automated backups with the --enable flag:

./hv backup schedule --enable

You can disable automated backups with the --disable flag:

./hv backup schedule --disable

Configuring the backup schedule

You can change the schedule at which automated backups take place. By default, automated backups happen daily at 2:00AM. To provide use a different cadence, you need to provide the schedule a cron expression. You can use an online cron expression generator tool to create a cron expression from human language.

Here's a few common example expressions:

• 0 2 * * *: Every day at 2:00 AM
• 0 0 * * 0: Every Sunday at midnight
• 0 0 1 * *: First day of each month at midnight

To configure the backup schedule, provide the --cron flag with the desired cron expression. For example, to take backups every other day at 2:00AM:

./hv backup schedule --cron "0 2 */2 * *"

Configuring Retention Policy

The backup system will prune older snapshots after each automated backup operation. You can control the amount of cloud storage used for backups by specifying how long backup snapshots should be kept.

To set a retention policy, you can use the backup schedule command, for example:

./hv backup schedule --retention 7D4W16M10Y

The retention policy format uses a combination of time units:

Examples:

• 7D4W16M10Y: Keep all daily snapshots for the past week, all weekly for the past month, all monthly for 16 months, and all yearly for 10 years
• 24H7D: Keep all hourly snapshots for the past day and all daily snapshots for the past week
• 7d: Keep only the most recent daily snapshot for the last week
• all: Keep all snapshots indefinitely

Managing Backup Snapshots

Listing Available Snapshots

To view all available backups:

./hv snapshots list

Browsing Snapshot Contents

To examine the contents of a specific backup:

./hv snapshots browse <snapshot_id>

Removing a Snapshot

If you need to delete a specific snapshot:

./hv snapshots forget <snapshot_id>

Use the --dry-run flag to preview the operation without actually deleting anything:

./hv snapshots forget <snapshot_id> --dry-run

Restoring from Backup

One of HomeVault's key advantages is its repeatable deployment architecture, which significantly simplifies the recovery process. When disaster strikes, whether it's a disk failure or a complete server loss, you can recover your entire HomeVault instance with minimal effort.

Restore From Snapshot

To restore your HomeVault instance from a backup, you need to have a server with enough storage capacity to hold the entire data that's included in the backup snapshot.

Step 1. Assuming the workspace you used for the original deployment no longer exists, you will need to recreate the workspace:

mkdir -p ~/homevault/workspace
cd ~/homevault/workspace
curl -fsSL https://github.com/thedebuggedlife/homevault-deployment/releases/latest/download/setup.zip | busybox unzip -n -
chmod +x hv

Step 2. You will need to re-create the restic.env file that was used when you initialized the backup system.

Step 3. Run the restore command:

./hv restore --snapshot <snapshot_id> --restic-env /path/to/your/restic-env-file

[!tip] If you don't specify a snapshot ID, the script will automatically use the latest available snapshot

To perform a dry run without actually restoring:

./homevault.sh restore --snapshot --restic-env /path/to/your/restic-env-file --dry-run

What Gets Restored From A Snapshot

During the restore process, HomeVault:

1. Downloads the selected snapshot from your cloud storage provider
2. Extracts app configuration and user data from the snapshot
3. Redeploys the modules that were active when the snapshot was created
4. Restores your data to its previous state

The only requirement is to have sufficient storage space on your server to accommodate the snapshot contents.

Encryption and Security

HomeVault's backup solution leverages restic's robust encryption model to ensure your data remains protected at all times. Every snapshot is encrypted using the password you provide during initialization (the RESTIC_PASSWORD value). This encryption happens client-side before any data leaves your server, meaning your unencrypted data never traverses the network or reaches the storage provider.

Even if an unauthorized party were to gain access to your backup repository they would only see encrypted chunks of data that are practically impossible to decrypt without your password. The repository structure, file names, file sizes, and metadata are all encrypted, leaving attackers with no useful information about your data. This zero-knowledge approach means you can safely store backups on any provider without compromising security, as long as you keep your RESTIC_PASSWORD secure.

Remember that this password is the key to all your backups—if it's lost, your backup data becomes permanently and irreversibly inaccessible, and if it's compromised, your backup data could be decrypted by others.