From 6dc21760f9aefaaec9ad1734a18a718c86a416a2 Mon Sep 17 00:00:00 2001 From: ibizaman Date: Wed, 22 Apr 2026 23:41:20 +0200 Subject: [PATCH] contract: fix backup and databasebackup documentation --- modules/contracts/backup/docs/default.md | 43 ++++++++----------- .../contracts/databasebackup/docs/default.md | 28 ++++++------ 2 files changed, 33 insertions(+), 38 deletions(-) diff --git a/modules/contracts/backup/docs/default.md b/modules/contracts/backup/docs/default.md index 9c0c1eb..7ead513 100644 --- a/modules/contracts/backup/docs/default.md +++ b/modules/contracts/backup/docs/default.md @@ -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} diff --git a/modules/contracts/databasebackup/docs/default.md b/modules/contracts/databasebackup/docs/default.md index f9f7384..e514b96 100644 --- a/modules/contracts/databasebackup/docs/default.md +++ b/modules/contracts/databasebackup/docs/default.md @@ -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}