diff --git a/modules/contracts/backup/docs/default.md b/modules/contracts/backup/docs/default.md index e0ba5d0..559f6c7 100644 --- a/modules/contracts/backup/docs/default.md +++ b/modules/contracts/backup/docs/default.md @@ -4,6 +4,11 @@ This NixOS contract represents a backup job that will backup one or more files or directories at a regular schedule. +It is a contract between a service that has files to be backed up +and a service that backs up files. +All options in this contract should be set by the former. +The latter will then use the values of those options to know what to backup. + ## Contract Reference {#backup-contract-options} These are all the options that are expected to exist for this contract to be respected. @@ -16,41 +21,85 @@ source: @OPTIONS_JSON@ ## Usage {#backup-contract-usage} -A service that can be backed up will provide a `backup` option, like for the [Vaultwarden service][vaultwarden-service-backup]. -What this option defines is an implementation detail of that service -but it will at least define what directories to backup +A service that can be backed up will provide a `backup` option. +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. -[vaultwarden-service-backup]: services-vaultwarden.html#services-vaultwarden-options-shb.vaultwarden.backup +Here is an example module defining such a `backup` option: ```nix -shb.<service>.backup -``` - -Let's assume a module implementing this contract is available under the `shb.<backup_impl>` variable. -Then, to actually backup the service, one would write: - -```nix -shb.<backup_impl>.instances."<service>" = shb.<service>.backup // { - enable = true; - - # Options specific to backup_impl +{ + options = { + myservice.backup = lib.mkOption { + type = contracts.backup; + readOnly = true; + default = { + user = "myservice"; + sourceDirectories = [ + "/var/lib/myservice" + ]; + }; + }; + }; }; ``` -Then, for extra caution, a second backup could be made using another module `shb.<backup_impl_2>`: +As you can see, NixOS modules are a bit abused to make contracts work. +Default values are set as well as the `readOnly` attribute to ensure those values stay as defined. + +Now, on the other side we have a service that uses this `backup` option and actually backs up files. +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: ```nix -shb.<backup_impl_2>.instances."<service>" = shb.<service>.backup // { +backupservice.instances.myservice = myservice.backup // { enable = true; - # Options specific to backup_impl_2 + 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`: + +```nix +backupservice.instances.myservice_2 = myservice.backup // { + enable = true; + + repository = { + path = "<remote path>"; + }; +}; +``` + +Or with another module `backupservice_2`! + ## Provided Implementations {#backup-contract-impl} +An implementation here is a service that understands the `backup` contract +and will backup the files accordingly. + One implementation is provided out of the box: - [Restic block](blocks-restic.html). A second one based on `borgbackup` is in progress. + +## Services Providing `backup` Option {#backup-contract-services} + +- <!-- [ -->Audiobookshelf<!-- ](services-audiobookshelf.html). --> (no manual yet) +- <!-- [ -->Deluge<!--](services-deluge.html). --> (no manual yet) +- <!-- [ -->Grocy<!--](services-grocy.html). --> (no manual yet) +- <!-- [ -->Hledger<!--](services-hledger.html). --> (no manual yet) +- <!-- [ -->Home Assistant<!--](services-home-assistant.html). --> (no manual yet) +- <!-- [ -->Jellyfin<!--](services-jellyfin.html). --> (no manual yet) +- <!-- [ -->LLDAP<!--](blocks-ldap.html). --> (no manual yet) +- [Nextcloud](services-nextcloud.html#services-nextcloud-server-usage-backup). +- [Vaultwarden](services-vaultwarden.html#services-vaultwarden-backup). +- <!-- [ -->*arr<!--](services-arr.html). --> (no manual yet) diff --git a/modules/services/nextcloud-server/docs/default.md b/modules/services/nextcloud-server/docs/default.md index fc2e9c3..4d69464 100644 --- a/modules/services/nextcloud-server/docs/default.md +++ b/modules/services/nextcloud-server/docs/default.md @@ -275,9 +275,19 @@ shb.nextcloud.postgresSettings = { }; ``` -### Backup the Nextcloud data {#services-nextcloud-server-usage-backup} +### Backup {#services-nextcloud-server-usage-backup} -TODO +Backing up Nextcloud using the [Restic block](blocks-restic.html) is done like so: + +```nix +shb.restic.instances."nextcloud" = config.shb.nextcloud.backup // { + enable = true; +}; +``` + +The name `"nextcloud"` in the `instances` can be anything. +The `config.shb.nextcloud.backup` option provides what directories to backup. +You can define any number of Restic instances to backup Nextcloud multiple times. ### Enable Preview Generator App {#services-nextcloud-server-usage-previewgenerator}