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

doc: copy readme to preface

Browse source
This commit is contained in:
ibizaman 2025-12-02 23:14:18 +01:00
parent 90dcf8e86b
commit 3cd9e1684b
3 changed files with 372 additions and 42 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -289,7 +289,7 @@ shb.forgejo = {
As you can see, they are pretty similar! As you can see, they are pretty similar!
This makes setting up a new service pretty easy and intuitive. This makes setting up a new service pretty easy and intuitive.
SelfHostBlocks provides an ever growing list of [services](#provided-services) SelfHostBlocks provides an ever growing list of [services](#services)
that are configured in the same way. that are configured in the same way.
### Contracts ### Contracts

361
docs/preface.md
View file

@ -10,22 +10,203 @@ Feel free to join the dedicated Matrix room
[matrix.org#selfhostblocks](https://matrix.to/#/#selfhostblocks:matrix.org). [matrix.org#selfhostblocks](https://matrix.to/#/#selfhostblocks:matrix.org).
::: :::
Self Host Blocks intends to help you self host any service you would like SelfHostBlocks is:
with best practices out of the box.
Compared to the stock nixpkgs experience, Self Host Blocks provides - Your escape from the cloud, for privacy and data sovereignty enthusiast. [Why?](#preface-why-self-hosting)
an unified interface to setup common dependencies, called blocks - A groupware to self-host [all your data](#preface-services): documents, pictures, calendars, contacts, etc.
in this project: - An opinionated NixOS server management OS for a [safe self-hosting experience](#preface-features).
- A NixOS distribution making sure all services build and work correctly thanks to NixOS VM tests.
- A collection of NixOS modules standardizing options so configuring services [look the same](#preface-unified-interfaces).
- A testing ground for [contracts](#preface-contracts) which intents to make nixpkgs modules more modular.
- [Upstreaming][] as much as possible.
- reverse proxy [upstreaming]: https://github.com/pulls?page=1&q=created%3A%3E2023-06-01+is%3Apr+author%3Aibizaman+archived%3Afalse+-repo%3Aibizaman%2Fselfhostblocks+-repo%3Aibizaman%2Fskarabox
- TLS certificate management
- serving service under subdomain ## Why Self-Hosting {#preface-why-self-hosting}
- backup
It is obvious by now that
a deep dependency on proprietary service providers - "the cloud" -
is a significant liability.
One aspect often talked about is privacy
which is inherently not guaranteed when using a proprietary service
and is a valid concern.
A more punishing issue is having your account closed or locked
without prior warning
When that happens,
you get an instantaneous sinking feeling in your stomach
at the realization you lost access to your data,
possibly without recourse.
Hosting services yourself is the obvious alternative
to alleviate those concerns
but it tends to require a lot of technical skills and time.
SelfHostBlocks (together with its sibling project [Skarabox][])
aims to lower the bar to self-hosting,
and provides an opinionated server management system based on NixOS modules
embedding best practices.
Contrary to other server management projects,
its main focus is ease of long term maintenance
before ease of installation.
To achieve this, it provides building blocks to setup services.
Some are already provided out of the box,
and customizing or adding additional ones is done easily.
The building blocks fit nicely together thanks to [contracts](#contracts)
which SelfHostBlocks sets out to introduce into nixpkgs.
This will increase modularity, code reuse
and empower end users to assemble components
that fit together to build their server.
## Usage {#preface-usage}
> **Caution:** You should know that although I am using everything in this repo for my personal
> production server, this is really just a one person effort for now and there are most certainly
> bugs that I didn't discover yet.
To get started using SelfHostBlocks, the following snippet is enough:
```nix
{
inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks";
outputs = { selfhostblocks, ... }: let
system = "x86_64-linux";
nixpkgs' = selfhostblocks.lib.${system}.patchedNixpkgs;
in
nixosConfigurations = {
myserver = nixpkgs'.nixosSystem {
inherit system;
modules = [
selfhostblocks.nixosModules.default
./configuration.nix
];
};
};
}
```
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
[deploy-rs]: https://shb.skarabox.com/usage.html#usage-example-deployrs
[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 [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 :)
### Installation From Scratch {#preface-usage-installation-from-scratch}
I do recommend for this my sibling project [Skarabox][]
which bootstraps a new server and sets up a few tools:
- Create a bootable ISO, installable on an USB key.
- Handles one or two (in raid 1) SSDs for root partition.
- Handles two (in raid 1) or more hard drives for data partition.
- [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to install NixOS headlessly.
- [disko](https://github.com/nix-community/disko) to format the drives using native ZFS encryption with remote unlocking through ssh.
- [sops-nix](https://github.com/Mic92/sops-nix) to handle secrets.
- [deploy-rs](https://github.com/serokell/deploy-rs) to deploy updates.
[Skarabox]: https://github.com/ibizaman/skarabox
## Features {#preface-features}
SelfHostBlocks provides building blocks that take care of common self-hosting needs:
- Backup for all services.
- Automatic creation of ZFS datasets per service.
- LDAP and SSO integration for most services.
- Monitoring with Grafana and Prometheus stack with provided dashboards.
- Automatic reverse proxy and certificate management for HTTPS.
- VPN and proxy tunneling services.
Great care is taken to make the proposed stack robust.
This translates into a test suite comprised of automated NixOS VM tests
which includes playwright tests to verify some important workflow
like logging in.
This test suite also serves as a guaranty that all services provided by SelfHostBlocks
all evaluate, build and work correctly together. It works similarly as a distribution but here it's all [automated](#preface-updates).
Also, the stack fits together nicely thanks to [contracts](#preface-contracts).
### Services {#preface-services}
[Provided services](https://shb.skarabox.com/services.html) are:
- Nextcloud
- Audiobookshelf
- Deluge + *arr stack
- Forgejo
- Grocy
- Hledger
- Home-Assistant
- Jellyfin
- Karakeep
- Open WebUI
- Pinchflat
- Vaultwarden
Like explained above, those services all benefit from
out of the box backup,
LDAP and SSO integration,
monitoring with Grafana,
reverse proxy and certificate management
and VPN integration for the *arr suite.
Some services do not have an entry yet in the manual.
To know options for those, the only way for now
is to go to the [All Options][] section of the manual.
[All Options]: https://shb.skarabox.com/options.html
### Blocks {#preface-blocks}
The services above rely on the following [common blocks][]
which altogether provides a solid foundation for self-hosting services:
- Authelia
- BorgBackup
- Davfs
- LDAP - LDAP
- SSO. - Monitoring (Grafana - Prometheus - Loki stack)
- Nginx
- PostgreSQL
- Restic
- Sops
- SSL
- Tinyproxy
- VPN
- ZFS
Those blocks can be used with services
not provided by SelfHostBlocks as shown [in the manual][common blocks].
[common blocks]: https://shb.skarabox.com/blocks.html
The manual also provides documentation for each individual blocks.
### Unified Interfaces {#preface-unified-interfaces}
Thanks to the blocks,
SelfHostBlocks provides an unified configuration interface
for the services it provides.
Compare the configuration for Nextcloud and Forgejo. Compare the configuration for Nextcloud and Forgejo.
The following snippets focus on similitudes and assume the relevant blocks are configured off-screen. The following snippets focus on similitudes and assume the relevant blocks - like secrets - are configured off-screen.
It also does not show specific options for each service.
These are still complete snippets that configure HTTPS,
subdomain serving the service, LDAP and SSO integration.
```nix ```nix
shb.nextcloud = { shb.nextcloud = {
@ -78,43 +259,147 @@ shb.forgejo = {
}; };
``` ```
SHB facilitates testing NixOS and slowly switching an existing installation to NixOS. As you can see, they are pretty similar!
This makes setting up a new service pretty easy and intuitive.
To achieve this, SHB pioneers [contracts][] SelfHostBlocks provides an ever growing list of [services](#preface-services)
which allows you, the final user, to be more in control of which piece go where. that are configured in the same way.
### Contracts {#preface-contracts}
To make building blocks that fit nicely together,
SelfHostBlocks pioneers [contracts][] which allows you, the final user,
to be more in control of which piece goes where.
This lets you choose, for example, This lets you choose, for example,
any reverse proxy you want or any database you want, any reverse proxy you want or any database you want,
without requiring work from maintainers of the services you want to self host. without requiring work from maintainers of the services you want to self host.
[contracts]: contracts.html An [RFC][] exists to upstream this concept into `nixpkgs`.
The [manual][contracts] also provides an explanation of the why and how of contracts.
To achieve this, Self Host Blocks provides building blocks Also, two videos exist of me presenting the topic,
which each provide part of what a self hosted app should do (SSO, HTTPS, etc.). the first at [NixCon North America in spring of 2024][NixConNA2024]
It also provides some services that are already integrated with all those building blocks. and the second at [NixCon in Berlin in fall of 2024][NixConBerlin2024].
Self Host Blocks uses the full power of NixOS modules to achieve these goals. [contracts]: https://shb.skarabox.com/contracts.html
Blocks and service are both NixOS modules. [RFC]: https://github.com/NixOS/rfcs/pull/189
[NixConNA2024]: https://www.youtube.com/watch?v=lw7PgphB9qM
[NixConBerlin2024]: https://www.youtube.com/watch?v=CP0hR6w1csc
## Next Steps {#next-steps} ### Interfacing With Other OSes {#preface-interface}
To get started using SelfHostBlocks, Thanks to [contracts](#contracts), one can interface NixOS
follow [the usage section](https://shb.skarabox.com/usage.html) of the manual. with systems on other OSes.
It goes over how to deploy with [Colmena][], [nixos-rebuild][] and [deploy-rs][] The [RFC][] explains how that works.
and also goes over secrets management with [SOPS][].
[Colmena]: https://shb.skarabox.com/usage.html#usage-example-colmena ### Sitting on the Shoulders of a Giant {#preface-giants}
[nixos-rebuild]: https://shb.skarabox.com/usage.html#usage-example-nixosrebuild
[deploy-rs]: https://shb.skarabox.com/usage.html#usage-example-deployrs
[SOPS]: https://shb.skarabox.com/usage.html#usage-secrets
Then, depending on what you want to do: By using SelfHostBlocks, you get all the benefits of NixOS
which are, for self hosted applications specifically:
- You are new to self hosting and want pre-configured services to deploy easily. - declarative configuration;
Look at the [services section](services.html). - atomic configuration rollbacks;
- You are a seasoned self-hoster but want to enhance some services you deploy already. - real programming language to define configurations;
Go to the [blocks section](blocks.html) and the [recipes section](recipes.html). - create your own higher level abstractions on top of SelfHostBlocks;
- You are a user of Self Host Blocks but would like to use your own implementation for a block. - integration with the rest of nixpkgs;
Go to the [contracts section](https://shb.skarabox.com/contracts.html). - much fewer "works on my machine" type of issues.
Head over to the [matrix channel](https://matrix.to/#/#selfhostblocks:matrix.org) ### Automatic Updates {#preface-updates}
for any remaining question, or just to say hi :)
SelfHostBlocks follows nixpkgs unstable branch closely.
There is a GitHub action running every couple of days that updates
the `nixpkgs` input in the root `flakes.nix`,
runs the tests and merges the PR automatically
if the tests pass.
A release is then made every few commits,
whenever deemed sensible.
On your side, to update I recommend pinning to a release
with the following command,
replacing the RELEASE with the one you want:
```bash
RELEASE=0.2.4
nix flake update \
--override-input selfhostblocks github:ibizaman/selfhostblocks/$RELEASE \
selfhostblocks
```
### Demos {#preface-demos}
Demos that start and deploy a service
on a Virtual Machine on your computer are located
under the [demo](./demo/) folder.
These show the onboarding experience you would get
if you deployed one of the services on your own server.
## Roadmap {#preface-roadmap}
Currently, the Nextcloud and Vaultwarden services
and the SSL and backup blocks
are the most advanced and most documented.
Documenting all services and blocks will be done
as I make all blocks and services use the contracts.
Upstreaming changes is also on the roadmap.
Check the [issues][] and the [milestones]() to see planned work.
Feel free to add more or to contribute!
[issues]: (https://github.com/ibizaman/selfhostblocks/issues)
[milestones]: https://github.com/ibizaman/selfhostblocks/milestones
All blocks and services have NixOS tests.
Also, I am personally using all the blocks and services in this project, so they do work to some extent.
## Community {#preface-community}
This project has been the main focus
of my (non work) life for the past 3 year now
and I intend to continue working on this for a long time.
All issues and PRs are welcome:
- Use this project. Something does not make sense? Something's not working?
- Documentation. Something is not clear?
- New services. Have one of your preferred service not integrated yet?
- Better patterns. See something weird in the code?
For PRs, if they are substantial changes, please open an issue to
discuss the details first. More details in [the contributing section](https://shb.skarabox.com/contributing.html)
of the manual.
Issues that are being worked on are labeled with the [in progress][] label.
Before starting work on those, you might want to talk about it in the issue tracker
or in the [matrix][] channel.
The prioritized issues are those belonging to the [next milestone][milestone].
Those issues are not set in stone and I'd be very happy to solve
an issue an user has before scratching my own itch.
[in progress]: https://github.com/ibizaman/selfhostblocks/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22in%20progress%22
[matrix]: https://matrix.to/#/%23selfhostblocks%3Amatrix.org
[milestone]: https://github.com/ibizaman/selfhostblocks/milestones
One aspect that's close to my heart is I intent to make SelfHostBlocks the lightest layer on top of nixpkgs as
possible. I want to upstream as much as possible. I will still take some time to experiment here but
when I'm satisfied with how things look, I'll upstream changes.
## Funding {#preface-funding}
I was lucky to [obtain a grant][nlnet] from NlNet which is an European fund,
under [NGI Zero Core][NGI0],
to work on this project.
This also funds the contracts RFC.
Go apply for a grant too!
[nlnet]: https://nlnet.nl/project/SelfHostBlocks
[NGI0]: https://nlnet.nl/core/
## License {#preface-license}
I'm following the [Nextcloud](https://github.com/nextcloud/server) license which is AGPLv3.
See [this article](https://www.fsf.org/bulletin/2021/fall/the-fundamentals-of-the-agplv3) from the FSF that explains what this license adds to the GPL one.

51
docs/redirects.json
View file

@ -1967,9 +1967,6 @@
"native-prometheus-metrics": [ "native-prometheus-metrics": [
"service-implementation-guide.html#native-prometheus-metrics" "service-implementation-guide.html#native-prometheus-metrics"
], ],
"next-steps": [
"index.html#next-steps"
],
"nixpkgs-integration": [ "nixpkgs-integration": [
"service-implementation-guide.html#nixpkgs-integration" "service-implementation-guide.html#nixpkgs-integration"
], ],
@ -1979,6 +1976,54 @@
"preface": [ "preface": [
"index.html#preface" "index.html#preface"
], ],
"preface-blocks": [
"index.html#preface-blocks"
],
"preface-community": [
"index.html#preface-community"
],
"preface-contracts": [
"index.html#preface-contracts"
],
"preface-demos": [
"index.html#preface-demos"
],
"preface-features": [
"index.html#preface-features"
],
"preface-funding": [
"index.html#preface-funding"
],
"preface-giants": [
"index.html#preface-giants"
],
"preface-interface": [
"index.html#preface-interface"
],
"preface-license": [
"index.html#preface-license"
],
"preface-roadmap": [
"index.html#preface-roadmap"
],
"preface-services": [
"index.html#preface-services"
],
"preface-unified-interfaces": [
"index.html#preface-unified-interfaces"
],
"preface-updates": [
"index.html#preface-updates"
],
"preface-usage": [
"index.html#preface-usage"
],
"preface-usage-installation-from-scratch": [
"index.html#preface-usage-installation-from-scratch"
],
"preface-why-self-hosting": [
"index.html#preface-why-self-hosting"
],
"quick-reference": [ "quick-reference": [
"service-implementation-guide.html#quick-reference" "service-implementation-guide.html#quick-reference"
], ],