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. Such a service is a requester providing a request for a module provider of this contract.

What this option defines is, from the user perspective - that is you - an implementation detail but it will at least define what directories to backup, the user to backup with and possibly hooks to run before or after the backup job runs.

Here is an example module defining such a backup option:

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

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;
  
  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;
  
  settings = {
    enable = true;
  
    repository = {
      path = "<remote path>";
    };
  };
};

Or with another module backupservice_2!

Providers of the Backup Contract

• Restic block.
• Borgbackup block [WIP].

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)