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 committed by Pierre Penninckx
parent 96a8753548
commit ff20e56ae1
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}
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:
Here is an example module defining such a `backup` option,
which defines what directories to backup (`sourceDirectories`)
and the user to backup with (`user`).
```nix
{
options = {
myservice.backup = mkOption {
type = lib.types.submodule {
options = contracts.backup.request;
};
default = {
user = "myservice";
sourceDirectories = [
"/var/lib/myservice"
];
options = shb.contracts.backup.mkRequester {
user = "nextcloud";
sourceDirectories = [
"/var/lib/nextcloud"
];
};
};
};
};
@ -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.
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`.
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
backupservice.instances.myservice = {
request = myservice.backup;
backupService.instances.myservice = {
request = myservice.backup.request;
settings = {
enable = true;
@ -65,17 +60,17 @@ backupservice.instances.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.
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
backupservice.instances.myservice_2 = {
request = myservice.backup;
backupService.instances.myservice_2 = {
request = myservice.backup.request;
settings = {
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}
- [Restic block](blocks-restic.html).
- [Borgbackup block](blocks-borgbackup.html) [WIP].
- [Borgbackup block](blocks-borgbackup.html).
## 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}
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
but it will at least define how to create a database dump,
the user to backup with
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
{
options = {
myservice.databasebackup = mkOption {
type = contracts.databasebackup.request;
default = {
type = shb.contracts.databasebackup.mkRequester = {
user = "myservice";
backupCmd = ''
${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.
Let's assume such a module is available under the `databasebackupservice` option
and that one can create multiple backup instances under `databasebackupservice.instances`.
Let's assume such a module is available under the `databaseBackupService` option
and that one can create multiple backup instances under `databaseBackupService.instances`.
Then, to actually backup the `myservice` service, one would write:
```nix
databasebackupservice.instances.myservice = {
request = myservice.databasebackup;
databaseBackupService.instances.myservice = {
request = myservice.databasebackup.request;
settings = {
enable = true;
@ -72,11 +72,11 @@ databasebackupservice.instances.myservice = {
```
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
databasebackupservice.instances.myservice_2 = {
request = myservice.backup;
databaseBackupService.instances.myservice_2 = {
request = myservice.databasebackup.request;
settings = {
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}
- [Restic block](blocks-restic.html).
- [Borgbackup block](blocks-borgbackup.html) [WIP].
- [Borgbackup block](blocks-borgbackup.html).
## Requester Blocks and Services {#contract-databasebackup-requesters}