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

doc: add minimal example which is tested in CI

Browse source
This commit is contained in:
ibizaman 2025-10-28 11:53:16 +01:00 committed by Pierre Penninckx
parent a2b274ca80
commit 7b31e060a8
4 changed files with 179 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
.github/workflows/demo.yml vendored
View file

@ -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 \

37
README.md
View file

@ -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 :)

125
demo/minimal/flake.nix Normal file
View file

@ -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;
};
}
)
];
};
};
};
}

55
docs/usage.md
View file

@ -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}