hosting/selfhostblocks
1
0
Fork 0
Code Issues Activity

update documentation for backup contract

Browse source
This commit is contained in:
ibizaman 2024-08-23 22:48:10 +02:00
parent dd4a13ad43
commit 7bbe23e146
2 changed files with 79 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
modules/contracts/backup/docs/default.md
View file

@ -4,6 +4,11 @@ This NixOS contract represents a backup job
that will backup one or more files or directories that will backup one or more files or directories
at a regular schedule. 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} ## Contract Reference {#backup-contract-options}
These are all the options that are expected to exist for this contract to be respected. 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} ## Usage {#backup-contract-usage}
A service that can be backed up will provide a `backup` option, like for the [Vaultwarden service][vaultwarden-service-backup]. A service that can be backed up will provide a `backup` option.
What this option defines is an implementation detail of that service 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 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. 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 ```nix
shb.<service>.backup {
``` options = {
myservice.backup = lib.mkOption {
Let's assume a module implementing this contract is available under the `shb.<backup_impl>` variable. type = contracts.backup;
Then, to actually backup the service, one would write: readOnly = true;
default = {
```nix user = "myservice";
shb.<backup_impl>.instances."<service>" = shb.<service>.backup // { sourceDirectories = [
enable = true; "/var/lib/myservice"
];
# Options specific to backup_impl };
};
};
}; };
``` ```
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 ```nix
shb.<backup_impl_2>.instances."<service>" = shb.<service>.backup // { backupservice.instances.myservice = myservice.backup // {
enable = true; 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} ## 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: One implementation is provided out of the box:
- [Restic block](blocks-restic.html). - [Restic block](blocks-restic.html).
A second one based on `borgbackup` is in progress. 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)

14
modules/services/nextcloud-server/docs/default.md
View file

@ -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} ### Enable Preview Generator App {#services-nextcloud-server-usage-previewgenerator}