selfhostblocks/modules/contracts/backup/docs/default.md

Backup Contract

This NixOS contract represents a backup job that will backup one or more files or directories on a regular schedule.

It is a contract between a service that has files to be backed up and a service that backs up files.

Contract Reference

These are all the options that are expected to exist for this contract to be respected.

id-prefix: contracts-backup-options-
list-id: selfhostblocks-options
source: @OPTIONS_JSON@

Usage

A service that can be backed up will provide a backup option.

Here is an example module defining such a backup option, which defines what directories to backup (sourceDirectories) and the user to backup with (user).

{
  options = {
    myservice.backup = mkOption {
      type = lib.types.submodule {
        options = shb.contracts.backup.mkRequester {
          user = "nextcloud";
          sourceDirectories = [
            "/var/lib/nextcloud"
          ];
        };
      };
    };
  };
};

Now, on the other side we have a service that uses this backup option and actually backs up files. This service is a provider of this contract and will provide a result option.

Let's assume such a module is available under the backupService option and that one can create multiple backup instances under backupService.instances. Then, to actually backup the myservice service, one would write:

backupService.instances.myservice = {
  request = myservice.backup.request;
  
  settings = {
    enable = true;

    repository = {
      path = "/srv/backup/myservice";
    };

    # ... Other options specific to backupService like scheduling.
  };
};

It is advised to backup files to different location, to improve redundancy. Thanks to using contracts, this can be made easily either with the same backupService:

backupService.instances.myservice_2 = {
  request = myservice.backup.request;
  
  settings = {
    enable = true;
  
    repository = {
      path = "<remote path>";
    };
  };
};

Or with another module backupService_2!

Providers of the Backup Contract

• Restic block.
• Borgbackup block.
• ZFS block.

Requester Blocks and Services

• Audiobookshelf (no manual yet)
• Deluge (no manual yet)
• Grocy (no manual yet)
• Hledger (no manual yet)
• Home Assistant (no manual yet)
• Jellyfin (no manual yet)
• LLDAP (no manual yet)
• Nextcloud.
• Vaultwarden.
• *arr (no manual yet)