danvics/selfhostblocks
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

usage.md - nixos single machine example - fix typo

Browse source
This commit is contained in:
Mrid22 2025-10-28 19:57:43 +01:00 committed by Pierre Penninckx
parent b416841fba
commit abc9990f38
1 changed files with 124 additions and 108 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

232
docs/usage.md
View file

@ -1,17 +1,17 @@
<!-- Read these docs at https://shb.skarabox.com --> <!-- Read these docs at https://shb.skarabox.com -->
# Usage {#usage} # Usage {#usage}
## Flake {#usage-flake} ## Flake {#usage-flake}
::: {.note} ::: {.note} A complete minimal and buildable example can be found at
A complete minimal and buildable example can be found at [`./demo/minimal/flake.nix`](@REPO@/demo/minimal/flake.nix). :::
[`./demo/minimal/flake.nix`](@REPO@/demo/minimal/flake.nix).
:::
Self Host Blocks is available as a flake. It also uses its own `pkgs.lib` and `nixpkgs` Self Host Blocks is available as a flake. It also uses its own `pkgs.lib` and
and it is required to use the provided ones as input for your deployments, `nixpkgs` and it is required to use the provided ones as input for your
otherwise you might end up blocked when Self Host Blocks patches a module, function or package. deployments, otherwise you might end up blocked when Self Host Blocks patches a
The following snippet is thus required to use Self Host Blocks: module, function or package. The following snippet is thus required to use Self
Host Blocks:
```nix ```nix
{ {
@ -33,29 +33,35 @@ The following snippet is thus required to use Self Host Blocks:
} }
``` ```
If you use `sops-nix` for secrets, SHB provides an additional module, If you use `sops-nix` for secrets, SHB provides an additional module, not
not imported in the `default` module. It can be added by importing imported in the `default` module. It can be added by importing
`inputs.selfhostblocks.sops`. `inputs.selfhostblocks.sops`.
### SHB Lib {#usage-flake-lib} ### SHB Lib {#usage-flake-lib}
Providing patches to downstream users is finicky, to say the least. Providing patches to downstream users is finicky, to say the least. For example,
For example, using `selfhostblocks.inputs.nixpkgs` directly will _not_ work. using `selfhostblocks.inputs.nixpkgs` directly will _not_ work. So Self Host
So Self Host Blocks provides a few attributes under the `selfhostblocks.lib.${system}` flake output: Blocks provides a few attributes under the `selfhostblocks.lib.${system}` flake
output:
- At the top-level, all functions defined by SHB under [`./lib/default.nix`](@REPO@/lib/default.nix) and [`./test/common.nix`](@REPO@/test/common.nix). - At the top-level, all functions defined by SHB under
- `patches`: the list of patches applied by SHB [`./patches`](@REPO@/patches) to nixpkgs. [`./lib/default.nix`](@REPO@/lib/default.nix) and
[`./test/common.nix`](@REPO@/test/common.nix).
- `patches`: the list of patches applied by SHB [`./patches`](@REPO@/patches) to
nixpkgs.
- `contracts`: all contract modules. - `contracts`: all contract modules.
- `patchNixpkgs`: a re-export of `nixpkgs.legacyPackages.${system}.applyPatches` with the arguments made a bit more explicit. - `patchNixpkgs`: a re-export of `nixpkgs.legacyPackages.${system}.applyPatches`
with the arguments made a bit more explicit.
- `patchedNixpkgs`: nixpkgs with `patches` applied. - `patchedNixpkgs`: nixpkgs with `patches` applied.
- `pkgs`: `nixpkgs.legacyPackages.${system}` with `patches` applied and also: - `pkgs`: `nixpkgs.legacyPackages.${system}` with `patches` applied and also:
- `config.allowUnfree` set to `true` - `config.allowUnfree` set to `true`
- `lib.shb` holds functions defined by [`./lib/default.nix`](@REPO@/lib/default.nix) - `lib.shb` holds functions defined by
- `lib.evalModules` is patched to include patches provided by nixpkgs [`./lib/default.nix`](@REPO@/lib/default.nix)
- `nixosSystem` is patched to include patches provided by nixpkgs - `lib.evalModules` is patched to include patches provided by nixpkgs
- `nixosSystem` is patched to include patches provided by nixpkgs
For normal usage, one should only need the provided `.nixosSystem`, `.pkgs` For normal usage, one should only need the provided `.nixosSystem`, `.pkgs` and
and in some cases `.nixpkgs`. in some cases `.nixpkgs`.
### Substituter {#usage-flake-substituter} ### Substituter {#usage-flake-substituter}
@ -83,17 +89,18 @@ Updating Self Host Blocks to a new version can be done the same way.
### Auto Updates {#usage-flake-autoupdate} ### Auto Updates {#usage-flake-autoupdate}
To avoid burden on the maintainers to keep `nixpkgs` input updated with upstream, To avoid burden on the maintainers to keep `nixpkgs` input updated with
the [GitHub repository][repo] for Self Host Blocks updates the `nixpkgs` input every couple days, upstream, the [GitHub repository][repo] for Self Host Blocks updates the
and verifies all tests pass before automatically merging the new `nixpkgs` version. `nixpkgs` input every couple days, and verifies all tests pass before
The setup is explained in [this blog post][automerge]. automatically merging the new `nixpkgs` version. The setup is explained in
[this blog post][automerge].
[repo]: https://github.com/ibizaman/selfhostblocks [repo]: https://github.com/ibizaman/selfhostblocks
[automerge]: https://blog.tiserbox.com/posts/2023-12-25-automated-flake-lock-update-pull-requests-and-merging.html [automerge]: https://blog.tiserbox.com/posts/2023-12-25-automated-flake-lock-update-pull-requests-and-merging.html
### Use SelfHostBlocks' lib {#usage-lib} ### Use SelfHostBlocks' lib {#usage-lib}
Access any functions exposed by the [lib][] with this snippet: Access any functions exposed by the [lib][lib] with this snippet:
```nix ```nix
{ {
@ -114,9 +121,10 @@ Access any functions exposed by the [lib][] with this snippet:
## Example Deployment with Nixos-Rebuild {#usage-example-nixosrebuild} ## Example Deployment with Nixos-Rebuild {#usage-example-nixosrebuild}
The following snippets show how to deploy Self Host Blocks using the standard deployment system [nixos-rebuild][]. The following snippets show how to deploy Self Host Blocks using the standard
deployment system [nixos-rebuild][nixos-rebuild].
[nixos-rebuild]:https://nixos.org/manual/nixos/stable/#sec-changing-config [nixos-rebuild]: https://nixos.org/manual/nixos/stable/#sec-changing-config
```nix ```nix
{ {
@ -124,31 +132,33 @@ The following snippets show how to deploy Self Host Blocks using the standard de
selfhostblocks.url = "github:ibizaman/selfhostblocks"; selfhostblocks.url = "github:ibizaman/selfhostblocks";
}; };
outputs = { self, selfhostblocks }: { outputs = {
let self,
system = "x86_64-linux"; selfhostblocks,
lib = selfhostblocks.lib.${system}; }: let
system = "x86_64-linux";
lib = selfhostblocks.lib.${system};
nixpkgs' = lib.shb.patchedNixpkgs; nixpkgs' = lib.shb.patchedNixpkgs;
nixosSystem' = import "${nixpkgs'}/nixos/lib/eval-config.nix"; nixosSystem' = import "${nixpkgs'}/nixos/lib/eval-config.nix";
in in {
nixosConfigurations = { nixosConfigurations = {
machine = nixosSystem' { machine = nixosSystem' {
inherit system; inherit system;
modules = [ modules = [
selfhostblocks.nixosModules.default selfhostblocks.nixosModules.default
]; ];
};
}; };
};
}; };
} }
``` ```
The above snippet assumes one machine to deploy to, The above snippet assumes one machine to deploy to, so `nixpkgs` is defined
so `nixpkgs` is defined exclusively by the `selfhostblocks` input. exclusively by the `selfhostblocks` input. It is more likely that you have
It is more likely that you have multiple machines, multiple machines, some not using Self Host Blocks, then you can do the
some not using Self Host Blocks, then you can do the following: following:
```nix ```nix
{ {
@ -183,12 +193,14 @@ some not using Self Host Blocks, then you can do the following:
}; };
} }
``` ```
In the above snippet, `machine1` will use the `nixpkgs` version from your inputs In the above snippet, `machine1` will use the `nixpkgs` version from your inputs
while `machine2` will use the `nixpkgs` version from `selfhostblocks`. while `machine2` will use the `nixpkgs` version from `selfhostblocks`.
## Example Deployment With Colmena {#usage-example-colmena} ## Example Deployment With Colmena {#usage-example-colmena}
The following snippets show how to deploy Self Host Blocks using the deployment system [Colmena][]. The following snippets show how to deploy Self Host Blocks using the deployment
system [Colmena][Colmena].
[colmena]: https://colmena.cli.rs [colmena]: https://colmena.cli.rs
@ -224,11 +236,10 @@ The following snippets show how to deploy Self Host Blocks using the deployment
} }
``` ```
The above snippet assumes one machine to deploy to, The above snippet assumes one machine to deploy to, so `nixpkgs` is defined
so `nixpkgs` is defined exclusively by the `selfhostblocks` input. exclusively by the `selfhostblocks` input. It is more likely that you have
It is more likely that you have multiple machines, multiple machines, some not using Self Host Blocks, in this case you can use the
some not using Self Host Blocks, `colmena.meta.nodeNixpkgs` option:
in this case you can use the `colmena.meta.nodeNixpkgs` option:
```nix ```nix
{ {
@ -277,7 +288,8 @@ while `machine2` will use the `nixpkgs` version from `selfhostblocks`.
## Example Deployment with deploy-rs {#usage-example-deployrs} ## Example Deployment with deploy-rs {#usage-example-deployrs}
The following snippets show how to deploy Self Host Blocks using the deployment system [deploy-rs][]. The following snippets show how to deploy Self Host Blocks using the deployment
system [deploy-rs][deploy-rs].
[deploy-rs]: https://github.com/serokell/deploy-rs [deploy-rs]: https://github.com/serokell/deploy-rs
@ -340,11 +352,9 @@ The following snippets show how to deploy Self Host Blocks using the deployment
} }
``` ```
The above snippet assumes one machine to deploy to, The above snippet assumes one machine to deploy to, so `nixpkgs` is defined
so `nixpkgs` is defined exclusively by the `selfhostblocks` input. exclusively by the `selfhostblocks` input. It is more likely that you have
It is more likely that you have multiple machines, multiple machines, some not using Self Host Blocks, in this case you can do:
some not using Self Host Blocks,
in this case you can do:
```nix ```nix
{ {
@ -420,40 +430,44 @@ in this case you can do:
} }
``` ```
In the above snippet, `machine1` will use the `nixpkgs` version from your inputs while `machine2` In the above snippet, `machine1` will use the `nixpkgs` version from your inputs
will use the `nixpkgs` version from `selfhostblocks`. while `machine2` will use the `nixpkgs` version from `selfhostblocks`.
## Secrets with sops-nix {#usage-secrets} ## Secrets with sops-nix {#usage-secrets}
This section complements the official [sops-nix](https://github.com/Mic92/sops-nix) guide. This section complements the official
[sops-nix](https://github.com/Mic92/sops-nix) guide.
Managing secrets is an important aspect of deploying. You cannot store your secrets in nix directly Managing secrets is an important aspect of deploying. You cannot store your
because they get stored unencrypted and you don't want that. We need to use another system that secrets in nix directly because they get stored unencrypted and you don't want
encrypts secrets when storing in the nix store and then decrypts them on the target host upon system that. We need to use another system that encrypts secrets when storing in the
activation. `sops-nix` is one of such system. nix store and then decrypts them on the target host upon system activation.
`sops-nix` is one of such system.
Sops-nix works by encrypting the secrets file with at least 2 keys. Your private key and a private Sops-nix works by encrypting the secrets file with at least 2 keys. Your private
key from the target host. This way, you can edit the secrets and the target host can decrypt the key and a private key from the target host. This way, you can edit the secrets
secrets. Separating the keys this way is good practice because it reduces the impact of having one and the target host can decrypt the secrets. Separating the keys this way is
being compromised. good practice because it reduces the impact of having one being compromised.
One way to setup secrets management using `sops-nix`: One way to setup secrets management using `sops-nix`:
1. Create your own private key that will be located in `keys.txt`. The public key will be printed on stdout. 1. Create your own private key that will be located in `keys.txt`. The public
key will be printed on stdout.
```bash ```bash
$ nix shell nixpkgs#age --command age-keygen -o keys.txt $ nix shell nixpkgs#age --command age-keygen -o keys.txt
Public key: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7 Public key: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
``` ```
2. Get the target host's public key. We will use the key derived from the ssh key of the host. 2. Get the target host's public key. We will use the key derived from the ssh
key of the host.
```bash ```bash
$ nix shell nixpkgs#ssh-to-age --command \ $ nix shell nixpkgs#ssh-to-age --command \
sh -c 'ssh-keyscan -t ed25519 -4 <target_host> | ssh-to-age' sh -c 'ssh-keyscan -t ed25519 -4 <target_host> | ssh-to-age'
# localhost:2222 SSH-2.0-OpenSSH_9.6 # localhost:2222 SSH-2.0-OpenSSH_9.6
age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8 age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
``` ```
3. Create a `sops.yaml` file that explains how sops-nix should encrypt the - yet to be created - 3. Create a `sops.yaml` file that explains how sops-nix should encrypt the - yet
`secrets.yaml` file. You can be creative here, but a basic snippet is: to be created - `secrets.yaml` file. You can be creative here, but a basic
snippet is:
```bash ```bash
keys: keys:
- &me age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7 - &me age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
@ -465,45 +479,47 @@ One way to setup secrets management using `sops-nix`:
- *me - *me
- *target - *target
``` ```
4. Create a `secrets.yaml` file that will contain the encrypted secrets as a Yaml file: 4. Create a `secrets.yaml` file that will contain the encrypted secrets as a
Yaml file:
```bash ```bash
$ SOPS_AGE_KEY_FILE=keys.txt nix run --impure nixpkgs#sops -- \ $ SOPS_AGE_KEY_FILE=keys.txt nix run --impure nixpkgs#sops -- \
secrets.yaml secrets.yaml
``` ```
This will open your preferred editor. An example of yaml file is the following (secrets are elided for brevity): This will open your preferred editor. An example of yaml file is the
following (secrets are elided for brevity):
```yaml ```yaml
nextcloud: nextcloud:
adminpass: 43bb4b... adminpass: 43bb4b...
onlyoffice: onlyoffice:
jwt_secret: 3a10fce3... jwt_secret: 3a10fce3...
``` ```
The actual file on your filesystem will look like so, again with data elided: The actual file on your filesystem will look like so, again with data elided:
```yaml ```yaml
nextcloud: nextcloud:
adminpass: ENC[AES256_GCM,data:Tt99...GY=,tag:XlAqRYidkOMRZAPBsoeEMw==,type:str] adminpass: ENC[AES256_GCM,data:Tt99...GY=,tag:XlAqRYidkOMRZAPBsoeEMw==,type:str]
onlyoffice: onlyoffice:
jwt_secret: ENC[AES256_GCM,data:f87a...Yg=,tag:Y1Vg2WqDnJbl1Xg2B6W1Hg==,type:str] jwt_secret: ENC[AES256_GCM,data:f87a...Yg=,tag:Y1Vg2WqDnJbl1Xg2B6W1Hg==,type:str]
sops: sops:
kms: [] kms: []
gcp_kms: [] gcp_kms: []
azure_kv: [] azure_kv: []
hc_vault: [] hc_vault: []
age: age:
- recipient: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7 - recipient: age1algdv9xwjre3tm7969eyremfw2ftx4h8qehmmjzksrv7f2qve9dqg8pug7
enc: | enc: |
-----BEGIN AGE ENCRYPTED FILE----- -----BEGIN AGE ENCRYPTED FILE-----
YWdl...6g== YWdl...6g==
-----END AGE ENCRYPTED FILE----- -----END AGE ENCRYPTED FILE-----
- recipient: age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8 - recipient: age13wgyyae8epyw894ugd0rjjljh0rm98aurvzmsapcv7d852g9r5lq0pqfx8
enc: | enc: |
-----BEGIN AGE ENCRYPTED FILE----- -----BEGIN AGE ENCRYPTED FILE-----
YWdl...RA== YWdl...RA==
-----END AGE ENCRYPTED FILE----- -----END AGE ENCRYPTED FILE-----
lastmodified: "2024-01-28T06:07:02Z" lastmodified: "2024-01-28T06:07:02Z"
mac: ENC[AES256_GCM,data:lDJh...To=,tag:Opon9lMZBv5S7rRhkGFuQQ==,type:str] mac: ENC[AES256_GCM,data:lDJh...To=,tag:Opon9lMZBv5S7rRhkGFuQQ==,type:str]
pgp: [] pgp: []
unencrypted_suffix: _unencrypted unencrypted_suffix: _unencrypted
version: 3.8.1 version: 3.8.1
``` ```
To actually create random secrets, you can use: To actually create random secrets, you can use:
@ -526,15 +542,15 @@ One way to setup secrets management using `sops-nix`:
shb.sops.secrets."nextcloud/adminpass".request = config.shb.nextcloud.adminPass.request; shb.sops.secrets."nextcloud/adminpass".request = config.shb.nextcloud.adminPass.request;
shb.nextcloud.adminPass.result = config.shb.sops.secrets."nextcloud/adminpass".result; shb.nextcloud.adminPass.result = config.shb.sops.secrets."nextcloud/adminpass".result;
``` ```
The above snippet uses the [secrets contract](./contracts-secret.html) The above snippet uses the [secrets contract](./contracts-secret.html) and
and [sops block](./blocks-sops.html) to ease the configuration. [sops block](./blocks-sops.html) to ease the configuration.
## Complete Example {#usage-complete-example} ## Complete Example {#usage-complete-example}
This is my own config, which is using Self Host Blocks This is my own config, which is using Self Host Blocks as well as
as well as [Skarabox][], my sibling project used to bootstrap a server. [Skarabox][Skarabox], my sibling project used to bootstrap a server.
[Skarabox]: https://github.com/ibizaman/skarabox [Skarabox]: https://github.com/ibizaman/skarabox
`flake.nix` `flake.nix`