From 7b31e060a81039ae7f694c556afe9c413cdaea63 Mon Sep 17 00:00:00 2001 From: ibizaman Date: Tue, 28 Oct 2025 11:53:16 +0100 Subject: [PATCH] doc: add minimal example which is tested in CI --- .github/workflows/demo.yml | 12 ++++ README.md | 37 ++++++++--- demo/minimal/flake.nix | 125 +++++++++++++++++++++++++++++++++++++ docs/usage.md | 55 +++++----------- 4 files changed, 179 insertions(+), 50 deletions(-) create mode 100644 demo/minimal/flake.nix diff --git a/.github/workflows/demo.yml b/.github/workflows/demo.yml index b16b652..9afad79 100644 --- a/.github/workflows/demo.yml +++ b/.github/workflows/demo.yml @@ -54,6 +54,13 @@ jobs: - name: nextcloud flake: sso + - name: minimal + flake: minimal + - name: minimal + flake: lowlevel + - name: minimal + flake: sops + runs-on: ubuntu-latest steps: @@ -78,6 +85,11 @@ jobs: run: | cd demo/${{ matrix.demo.name }} nix flake update --override-input selfhostblocks ../.. selfhostblocks + nix \ + --print-build-logs \ + --option keep-going true \ + --show-trace \ + build .#nixosConfigurations.${{ matrix.demo.flake }}.config.system.build.toplevel nix \ --print-build-logs \ --option keep-going true \ diff --git a/README.md b/README.md index 37d125f..a2d4518 100644 --- a/README.md +++ b/README.md @@ -90,18 +90,33 @@ that fit together to build their server. > production server, this is really just a one person effort for now and there are most certainly > bugs that I didn't discover yet. -### At a Glance +To get started using SelfHostBlocks, the following snippet is enough: -Head over to the [recipes section](https://shb.skarabox.com/recipes.html) of the manual to see how SelfHostBlocks can help you quickly setup common use cases. +```nix +{ + inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks"; -The [services section](https://shb.skarabox.com/services.html) lists all integrated services you can quickly spin up using SelfHostBlocks. + outputs = { selfhostblocks, ... }: let + system = "x86_64-linux"; + shb = selfhostblocks.lib.${system}; + in + nixosConfigurations = { + myserver = shb.pkgs.nixosSystem { + inherit system; + modules = [ + selfhostblocks.nixosModules.default + ./configuration.nix + ]; + }; + }; +} +``` -### Existing Installation - -To get started using SelfHostBlocks, -follow [the usage section](https://shb.skarabox.com/usage.html) of the manual. -It goes over how to deploy with [Colmena][], [nixos-rebuild][] and [deploy-rs][] -and also goes over secrets management with [SOPS][]. +SelfHostBlocks provides its own patched nixpkgs, so you are required to use it +otherwise evaluation can quickly break. +[The usage section](https://shb.skarabox.com/usage.html) of the manual has +more details and goes over how to deploy with [Colmena][], [nixos-rebuild][] and [deploy-rs][] +and also how to handle secrets management with [SOPS][]. [Colmena]: https://shb.skarabox.com/usage.html#usage-example-colmena [nixos-rebuild]: https://shb.skarabox.com/usage.html#usage-example-nixosrebuild @@ -109,9 +124,11 @@ and also goes over secrets management with [SOPS][]. [SOPS]: https://shb.skarabox.com/usage.html#usage-secrets Then, to actually configure services, you can choose which one interests you in -[the services section](https://shb.skarabox.com/services.html) of the manual. +the [services section](https://shb.skarabox.com/services.html) of the manual. Not all services have a corresponding manual page yet. +The [recipes section](https://shb.skarabox.com/recipes.html) of the manual shows some other common use cases. + Head over to the [matrix channel](https://matrix.to/#/#selfhostblocks:matrix.org) for any remaining question, or just to say hi :) diff --git a/demo/minimal/flake.nix b/demo/minimal/flake.nix new file mode 100644 index 0000000..1921b2f --- /dev/null +++ b/demo/minimal/flake.nix @@ -0,0 +1,125 @@ +{ + description = "Minimal example to setup SelfHostBlocks"; + + inputs = { + selfhostblocks.url = "github:ibizaman/selfhostblocks"; + + sops-nix = { + url = "github:Mic92/sops-nix"; + }; + }; + + outputs = + { + self, + selfhostblocks, + sops-nix, + }: + { + nixosConfigurations = + let + system = "x86_64-linux"; + shb = selfhostblocks.lib.${system}; + + # This module makes the assertions happy and the build succeed. + # This is of course wrong and will not work on any real system. + filesystemModule = { + fileSystems."/".device = "/dev/null"; + boot.loader.grub.devices = [ "/dev/null" ]; + }; + in + { + # Test with: + # nix build .#nixosConfigurations.minimal.config.system.build.toplevel + minimal = shb.pkgs.nixosSystem { + inherit system; + modules = [ + selfhostblocks.nixosModules.default + filesystemModule + # This modules showcases the use of SHB's lib. + ( + { config, lib, ... }: + { + options.myOption = lib.mkOption { + # Using provided nixosSystem directly + # SHB's lib is available under `lib.shb`. + type = lib.shb.secretFileType; + }; + config = { + myOption.source = "/a/path"; + # Use the option. + environment.etc.myOption.text = config.myOption.source; + }; + } + ) + ]; + }; + + # Test with: + # nix build .#nixosConfigurations.sops.config.system.build.toplevel + # nix eval .#nixosConfigurations.sops.config.myOption + sops = shb.pkgs.nixosSystem { + inherit system; + modules = [ + selfhostblocks.nixosModules.default + selfhostblocks.nixosModules.sops + sops-nix.nixosModules.default + filesystemModule + # This modules showcases the use of SHB's lib. + ( + { config, lib, ... }: + { + options.myOption = lib.mkOption { + # Using provided nixosSystem directly + # SHB's lib is available under `lib.shb`. + type = lib.shb.secretFileType; + }; + config = { + myOption.source = "/a/path"; + # Use the option. + environment.etc.myOption.text = config.myOption.source; + }; + } + ) + ]; + }; + + # Note: this is just to show-off a common pitfall for more advanced user. + # Prefer using the `shb.pkgs.nixosSystem` function directly. + # + # Test with: + # nix build .#nixosConfigurations.lowlevel.config.system.build.toplevel + # nix eval .#nixosConfigurations.lowlevel.config.myOption + lowlevel = + let + # We must import nixosSystem directly from the patched nixpkgs + # otherwise we do not get the patches. + nixosSystem' = import "${shb.patchedNixpkgs}/nixos/lib/eval-config.nix"; + in + nixosSystem' { + inherit system; + modules = [ + selfhostblocks.nixosModules.default + filesystemModule + # This modules showcases the use of SHB's lib. + ( + { config, lib, ... }: + { + options.myOption = lib.mkOption { + # lib.shb.secretFileType is not available here, + # so we must pass around the shb flake input. + # type = shb.secretFileType; + type = shb.secretFileType; + }; + config = { + myOption.source = "/a/path"; + # Use the option. + environment.etc.myOption.text = config.myOption.source; + }; + } + ) + ]; + }; + }; + }; +} diff --git a/docs/usage.md b/docs/usage.md index 1d9253e..b6adfb0 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -3,38 +3,15 @@ ## Flake {#usage-flake} -Self Host Blocks is available as a flake. To use it in your project, add the following flake input: +::: {.note} +A complete minimal and buildable example can be found at +[`./demo/minimal/flake.nix`](@REPO@/demo/minimal/flake.nix). +::: -```nix -inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks"; -``` - -Then, in your `nixosConfigurations`, you can import all modules with: - -```nix -imports = [ - inputs.selfhostblocks.default -]; -``` - -or selectively import some with, for example: - -```nix -imports = [ - inputs.selfhostblocks.authelia - inputs.selfhostblocks.lldap - inputs.selfhostblocks.nextcloud -]; -``` - -If you use `sops-nix` for secrets, SHB provides an additional module, -not imported in the `default` module. It can be added by importing -`inputs.selfhostblocks.sops`. - -Self Host Blocks provides its own `pkgs.lib` and `nixpkgs`. -It is required to use the provided ones as input for your deployments, +Self Host Blocks is available as a flake. It also uses its own `pkgs.lib` and `nixpkgs` +and it is required to use the provided ones as input for your deployments, otherwise you might end up blocked when Self Host Blocks patches a module, function or package. -You need the following code wherever you would usually import `nixpkgs`: +The following snippet is thus required to use Self Host Blocks: ```nix { @@ -42,26 +19,24 @@ You need the following code wherever you would usually import `nixpkgs`: outputs = { selfhostblocks, ... }: let system = "x86_64-linux"; - shb = selfhostblocks.lib.${system}; - - nixpkgs' = import shb.nixpkgs { - inherit system; - }; in nixosConfigurations = { myserver = shb.pkgs.nixosSystem { - system = "x86_64-linux"; + inherit system; modules = [ + selfhostblocks.nixosModules.default ./configuration.nix ]; }; }; - - // elsewhere where nixpkgs is needed: } ``` +If you use `sops-nix` for secrets, SHB provides an additional module, +not imported in the `default` module. It can be added by importing +`inputs.selfhostblocks.sops`. + ### SHB Lib {#usage-flake-lib} Providing patches to downstream users is finicky, to say the least. @@ -79,8 +54,8 @@ So Self Host Blocks provides a few attributes under the `selfhostblocks.lib.${sy - `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 `selfhostblocks.lib.${system}.pkgs` -and in some cases `selfhostblocks.lib.${system}.nixpkgs`. +For normal usage, one should only need the provided `.nixosSystem`, `.pkgs` +and in some cases `.nixpkgs`. ### Substituter {#usage-flake-substituter}