add usage chapter in the manual

README.md

@@ -40,10 +40,10 @@ SHB provides also services that integrate with those blocks out of the box. Prog
 
 <!--toc:start-->
 - [Supported Features](#supported-features)
+- [Usage](#usage)
 - [Manual](#manual)
 - [Provided Services](#provided-services)
 - [Demos](#demos)
-- [Import selfhostblocks](#import-selfhostblocks)
 - [Community](#community)
 - [Tips](#tips)
 - [TODOs](#todos)
@@ -119,6 +119,45 @@ Currently supported services and features are:
   - [ ] Self published documentation for options.
   - [ ] Examples for all building blocks.
 
+## Usage
+
+The following snippet shows how to deploy to a machine (here `machine2`) using
+[Colmena](https://colmena.cli.rs):
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+
+    selfhostblocks.url = "github:ibizaman/selfhostblocks";
+  };
+
+  outputs = { self, selfhostblocks }: {
+    colmena = {
+      meta =
+        let
+          system = "x86_64-linux";
+        in {
+          nixpkgs = import nixpkgs { inherit system; };
+          nodeNixpkgs = {
+            machine2 = import selfhostblocks.inputs.nixpkgs { inherit system; };
+          };
+        };
+
+      machine1 = ...;
+
+      machine2 = { selfhostblocks, ... }: {
+        imports = [
+          selfhostblocks.nixosModules.${system}.default
+        ];
+      };
+    };
+  };
+}
+```
+
+More information is provided in the manual (see below).
+
 ## Manual
 
 The (WIP) complete manual can be found at [shb.skarabox.com](https://shb.skarabox.com/). The information in
@@ -477,64 +516,6 @@ Demos that start and deploy a service on a Virtual Machine on your computer are
 [demo](./demo/) folder. These show the onboarding experience you would get if you deployed
 one of the services on your own server.
 
-## Import selfhostblocks
-
-Ready to start using selfhostblocks? Thank you for trusting selfhostblocks. Please raise any
-question you have or hurdle you encounter by creating an issue.
-
-The top-level `flake.nix` just outputs a nixos module that gathers all other modules from
-the [`modules/`](./modules/) directory. Use this repo as a flake input to your own repo.
-The `inputs` field of your `flake.nix` file in your repo should look like so:
-
-```nix
-inputs = {
-  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-  sops-nix.url = "github:Mic92/sops-nix";
-
-  selfhostblocks.url = "github:ibizaman/selfhostblocks";
-  selfhostblocks.inputs.nixpkgs.follows = "nixpkgs";
-  selfhostblocks.inputs.sops-nix.follows = "sops-nix";
-};
-```
-
-`sops-nix` is used to setup passwords and secrets. Currently `selfhostblocks` has a strong
-dependency on it but I'm working on removing that so you could use any secret provider.
-
-The snippet above makes `selfhostblocks`' inputs follow yours. This is not maintainable though
-because options that `selfhostblocks` rely on can change or disappear and you have no control on
-that. Later, I intend to make `selfhostblocks` provide its own `nixpkgs` input and update it myself
-through CI.
-
-How you actually deploy using selfhostblocks depends on what system you choose. If you use
-[colmena](https://colmena.cli.rs), this is what your `outputs` field could look like:
-
-```nix
-outputs = inputs@{ self, nixpkgs, ... }: {
-  colmena = {
-    meta = {
-      nixpkgs = import inputs.nixpkgs {
-        system = "x86_64-linux";
-      };
-      specialArgs = inputs;
-    };
-
-    myserver = import ./machines/myserver.nix;
-  };
-}
-```
-
-Now, what goes inside this `./machines/myserver.nix` file? First, import `selfhostblocks` and
-`sops-nix`:
-
-```nix
-imports = [
-  selfhostblocks.nixosModules.x86_64-linux.default
-  sops-nix.nixosModules.default
-]
-```
-
-For the rest, see the above [building blocks](#building-blocks), [provided services](#provided-services) and [demos](#demos) sections.
-
 ## Community
 
 All issues and PRs are welcome. For PRs, if they are substantial changes, please open an issue to discuss the details first.

docs/manual.md

@@ -7,6 +7,10 @@
 preface.md
 ```
 
+```{=include=} chapters html:into-file=//usage.html
+usage.md
+```
+
 ```{=include=} chapters html:into-file=//services.html
 services.md
 ```

docs/usage.md

@@ -0,0 +1,95 @@
+# Usage {#usage}
+
+## Flake {#usage-flake}
+
+Self Host Blocks is available as a flake. To use it in your project, add the following flake input:
+
+```nix
+inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks";
+```
+
+Self Host Blocks provides its own `nixpkgs` input so both can be updated in lock step, ensuring
+maximum compatibility. It is recommended to use the following `nixpkgs` as input for your deployments:
+
+```nix
+inputs.selfhostblocks.inputs.nixpkgs
+```
+
+Advanced users can if they wish use a version of `nixpkgs` of their choosing but then we cannot
+guarantee Self Host Block won't use a non-existing option from `nixpkgs`.
+
+To avoid manually updating the `nixpkgs` version, the [GitHub repository][1] for Self Host Blocks
+tries to update the `nixpkgs` input daily, verifying all tests pass before accepting this new
+`nixpkgs` version. The setup is explained in [this blog post][2].
+
+[1]: https://github.com/ibizaman/selfhostblocks
+[2]: https://blog.tiserbox.com/posts/2023-12-25-automated-flake-lock-update-pull-requests-and-merging.html
+
+## Example Deployment With Colmena {#usage-example-colmena}
+
+The following snippets show how to deploy Self Host Blocks using the deployment system [Colmena][3].
+
+[3]: https://colmena.cli.rs
+
+```nix
+{
+  inputs = {
+    selfhostblocks.url = "github:ibizaman/selfhostblocks";
+  };
+
+  outputs = { self, selfhostblocks }: {
+    colmena = {
+      meta =
+        let
+          system = "x86_64-linux";
+        in {
+          nixpkgs = import selfhostblocks.inputs.nixpkgs { inherit system; };
+        };
+
+      machine = { selfhostblocks, ... }: {
+        imports = [
+          selfhostblocks.nixosModules.${system}.default
+        ];
+      };
+    };
+  };
+}
+```
+
+The above snippet is very minimal as it assumes you have only one machine to deploy to, so `nixpkgs`
+is defined exclusively by the `selfhostblocks` input. It is more likely that you have multiple machines, in this case you can use the `colmena.meta.nodeNixpkgs` option:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+
+    selfhostblocks.url = "github:ibizaman/selfhostblocks";
+  };
+
+  outputs = { self, selfhostblocks }: {
+    colmena = {
+      meta =
+        let
+          system = "x86_64-linux";
+        in {
+          nixpkgs = import nixpkgs { inherit system; };
+          nodeNixpkgs = {
+            machine2 = import selfhostblocks.inputs.nixpkgs { inherit system; };
+          };
+        };
+
+      machine1 = ...;
+
+      machine2 = { selfhostblocks, ... }: {
+        imports = [
+          selfhostblocks.nixosModules.${system}.default
+        ];
+      };
+    };
+  };
+}
+```
+
+In the above snippet, `machine1` will use the `nixpkgs` version from your inputs while `machine2`
+will use the `nixpkgs` version from `selfhostblocks`.

modules/blocks/backup/docs/default.md

@@ -11,9 +11,9 @@ Two implementations for this block are provided:
 
 No integration tests are provided yet.
 
-## Usage {#usage}
+## Usage {#blocks-backup-usage}
 
-### One folder backed up to mounted hard drives {#blocks-backup-config-one}
+### One folder backed up to mounted hard drives {#blocks-backup-usage-one}
 
 The following snippet shows how to configure backup of 1 folder using the Restic implementation to 1
 repository.
@@ -79,7 +79,7 @@ borgmatic:
 
 You can have both borgmatic and restic implementations working at the same time.
 
-### One folder backed up to S3 {#blocks-backup-config-remote}
+### One folder backed up to S3 {#blocks-backup-usage-remote}
 
 > This is only supported by the Restic implementation. 
 
@@ -117,7 +117,7 @@ The Sops file has a new required field:
 +             AWS_SECRET_ACCESS_KEY=<aws_secret_key>
 ```
 
-### Multiple folder to multiple destinations {#blocks-backup-config-multiple}
+### Multiple folder to multiple destinations {#blocks-backup-usage-multiple}
 
 The following snippet shows how to configure backup of any number of folders using the Restic
 implementation to 3 repositories, each happening at different times to avoid contending for I/O
@@ -214,18 +214,18 @@ shb.backup.instances.all = backupcfg repos ["/var/lib/myfolder1" "/var/lib/myfol
 Head over to the [Home Assistant demo](demo-homeassistant.html) for a demo that installs Home
 Assistant on a VM with minimal manual steps.
 
-## Monitoring {#monitoring-backup-block}
+## Monitoring {#blocks-backup-monitoring}
 
 [WIP]
 
-## Maintenance {#monitoring-maintenance}
+## Maintenance {#blocks-backup-maintenance}
 
 [WIP]
 
-## Options Reference {#opt-backup-block}
+## Options Reference {#blocks-backup-options}
 
 ```{=include=} options
-id-prefix: opt-blocks-backup-
+id-prefix: blocks-backup-options-
 list-id: selfhostblocks-block-backup-options
 source: @OPTIONS_JSON@
 ```