danvics/selfhostblocks
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

contract: fix backup and databasebackup documentation

Browse source
This commit is contained in:
ibizaman 2026-04-22 23:41:20 +02:00
parent 96a8753548
commit 6dc21760f9
2 changed files with 33 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -20,27 +20,22 @@ source: @OPTIONS_JSON@
## Usage {#contract-backup-usage} ## Usage {#contract-backup-usage}
A service that can be backed up will provide a `backup` option. 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 Here is an example module defining such a `backup` option,
but it will at least define what directories to backup, which defines what directories to backup (`sourceDirectories`)
the user to backup with and the user to backup with (`user`).
and possibly hooks to run before or after the backup job runs.
Here is an example module defining such a `backup` option:
```nix ```nix
{ {
options = { options = {
myservice.backup = mkOption { myservice.backup = mkOption {
type = lib.types.submodule { type = lib.types.submodule {
options = contracts.backup.request; options = shb.contracts.backup.mkRequester {
}; user = "nextcloud";
default = { sourceDirectories = [
user = "myservice"; "/var/lib/nextcloud"
sourceDirectories = [ ];
"/var/lib/myservice" };
];
}; };
}; };
}; };
@ -50,13 +45,13 @@ Here is an example module defining such a `backup` option:
Now, on the other side we have a service that uses this `backup` option and actually backs up files. 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. 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 Let's assume such a module is available under the `backupService` option
and that one can create multiple backup instances under `backupservice.instances`. and that one can create multiple backup instances under `backupService.instances`.
Then, to actually backup the `myservice` service, one would write: Then, to actually backup the `myservice` service, one would write:
```nix ```nix
backupservice.instances.myservice = { backupService.instances.myservice = {
request = myservice.backup; request = myservice.backup.request;
settings = { settings = {
enable = true; enable = true;
@ -65,17 +60,17 @@ backupservice.instances.myservice = {
path = "/srv/backup/myservice"; path = "/srv/backup/myservice";
}; };
# ... Other options specific to backupservice like scheduling. # ... Other options specific to backupService like scheduling.
}; };
}; };
``` ```
It is advised to backup files to different location, to improve redundancy. 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`: Thanks to using contracts, this can be made easily either with the same `backupService`:
```nix ```nix
backupservice.instances.myservice_2 = { backupService.instances.myservice_2 = {
request = myservice.backup; request = myservice.backup.request;
settings = { settings = {
enable = true; enable = true;
@ -87,12 +82,12 @@ backupservice.instances.myservice_2 = {
}; };
``` ```
Or with another module `backupservice_2`! Or with another module `backupService_2`!
## Providers of the Backup Contract {#contract-backup-providers} ## Providers of the Backup Contract {#contract-backup-providers}
- [Restic block](blocks-restic.html). - [Restic block](blocks-restic.html).
- [Borgbackup block](blocks-borgbackup.html) [WIP]. - [Borgbackup block](blocks-borgbackup.html).
## Requester Blocks and Services {#contract-backup-requesters} ## Requester Blocks and Services {#contract-backup-requesters}

28
modules/contracts/databasebackup/docs/default.md
View file

@ -20,21 +20,21 @@ source: @OPTIONS_JSON@
## Usage {#contract-databasebackup-usage} ## Usage {#contract-databasebackup-usage}
A database that can be backed up will provide a `databasebackup` option. A database that can be backed up will provide a `databasebackup` 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 What this option defines is, from the user perspective - that is _you_ - an implementation detail
but it will at least define how to create a database dump, but it will at least define how to create a database dump,
the user to backup with the user to backup with
and how to restore from a database dump. and how to restore from a database dump.
Here is an example module defining such a `databasebackup` option: Here is an example module defining such a `databasebackup` option,
which defines the user to backup with (`user`)
and how to backup (`backupCmd`) and restore (`restoreCmd`) the database:
```nix ```nix
{ {
options = { options = {
myservice.databasebackup = mkOption { myservice.databasebackup = mkOption {
type = contracts.databasebackup.request; type = shb.contracts.databasebackup.mkRequester = {
default = {
user = "myservice"; user = "myservice";
backupCmd = '' backupCmd = ''
${pkgs.postgresql}/bin/pg_dumpall | ${pkgs.gzip}/bin/gzip --rsyncable ${pkgs.postgresql}/bin/pg_dumpall | ${pkgs.gzip}/bin/gzip --rsyncable
@ -48,16 +48,16 @@ Here is an example module defining such a `databasebackup` option:
}; };
``` ```
Now, on the other side we have a service that uses this `backup` option and actually backs up files. Now, on the other side we have a service that uses this `databasebackup` option and actually backs up files.
This service is a `provider` of this contract and will provide a `result` option. This service is a `provider` of this contract and will provide a `result` option.
Let's assume such a module is available under the `databasebackupservice` option Let's assume such a module is available under the `databaseBackupService` option
and that one can create multiple backup instances under `databasebackupservice.instances`. and that one can create multiple backup instances under `databaseBackupService.instances`.
Then, to actually backup the `myservice` service, one would write: Then, to actually backup the `myservice` service, one would write:
```nix ```nix
databasebackupservice.instances.myservice = { databaseBackupService.instances.myservice = {
request = myservice.databasebackup; request = myservice.databasebackup.request;
settings = { settings = {
enable = true; enable = true;
@ -72,11 +72,11 @@ databasebackupservice.instances.myservice = {
``` ```
It is advised to backup files to different location, to improve redundancy. 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 `databasebackupservice`: Thanks to using contracts, this can be made easily either with the same `databaseBackupService`:
```nix ```nix
databasebackupservice.instances.myservice_2 = { databaseBackupService.instances.myservice_2 = {
request = myservice.backup; request = myservice.databasebackup.request;
settings = { settings = {
enable = true; enable = true;
@ -88,12 +88,12 @@ databasebackupservice.instances.myservice_2 = {
}; };
``` ```
Or with another module `databasebackupservice_2`! Or with another module `databaseBackupService_2`!
## Providers of the Database Backup Contract {#contract-databasebackup-providers} ## Providers of the Database Backup Contract {#contract-databasebackup-providers}
- [Restic block](blocks-restic.html). - [Restic block](blocks-restic.html).
- [Borgbackup block](blocks-borgbackup.html) [WIP]. - [Borgbackup block](blocks-borgbackup.html).
## Requester Blocks and Services {#contract-databasebackup-requesters} ## Requester Blocks and Services {#contract-databasebackup-requesters}