add usage chapter in the manual
This commit is contained in:
ibizaman
Pierre Penninckx
parent
4054b4b663
commit
7a62b5b89c
4 changed files with 147 additions and 67 deletions
99
README.md
99
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.
|
||||
|
|
|
|||
|
|
@ -7,6 +7,10 @@
|
|||
preface.md
|
||||
```
|
||||
|
||||
```{=include=} chapters html:into-file=//usage.html
|
||||
usage.md
|
||||
```
|
||||
|
||||
```{=include=} chapters html:into-file=//services.html
|
||||
services.md
|
||||
```
|
||||
|
|
|
|||
95
docs/usage.md
Normal file
95
docs/usage.md
Normal file
|
|
@ -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`.
|
||||
|
|
@ -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@
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue