From 7a62b5b89c406fbf80ac6dfb678c0d5c62a771ea Mon Sep 17 00:00:00 2001 From: ibizaman Date: Mon, 25 Dec 2023 23:23:55 -0800 Subject: [PATCH] add usage chapter in the manual --- README.md | 99 +++++++++++---------------- docs/manual.md | 4 ++ docs/usage.md | 95 +++++++++++++++++++++++++ modules/blocks/backup/docs/default.md | 16 ++--- 4 files changed, 147 insertions(+), 67 deletions(-) create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 35cd108..600dcc6 100644 --- a/README.md +++ b/README.md @@ -40,10 +40,10 @@ SHB provides also services that integrate with those blocks out of the box. Prog - [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. diff --git a/docs/manual.md b/docs/manual.md index f2385d5..6cbe2f2 100644 --- a/docs/manual.md +++ b/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 ``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..c42e085 --- /dev/null +++ b/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`. diff --git a/modules/blocks/backup/docs/default.md b/modules/blocks/backup/docs/default.md index 9405da5..73507e9 100644 --- a/modules/blocks/backup/docs/default.md +++ b/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= ``` -### 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@ ```