SelfHostBlocks is a NixOS based server management for self-hosting using building blocks and promoting best practices.
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 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.
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, follow the usage section of the manual. It goes over how to deploy with Colmena, nixos-rebuild and deploy-rs and also goes over secrets management with SOPS.
Then, to actually configure services, you can choose which one interests you in the services section of the manual. Not all services have a corresponding manual page yet.
Head over to the matrix channel for any remaining question, or just to say hi :)
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 to install NixOS headlessly.
- disko to format the drives using native ZFS encryption with remote unlocking through ssh.
- sops-nix to handle secrets.
- deploy-rs to deploy updates.
See full example in the manual.
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.
Also, the stack fits together nicely thanks to contracts.
Provided services are:
- Nextcloud
- Audiobookshelf
- Deluge + *arr stack
- Forgejo
- Grocy
- Hledger
- Home-Assistant
- Jellyfin
- 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.
The services above rely on the following common blocks:
- Authelia
- BorgBackup
- Davfs
- LDAP
- Monitoring (Grafana - Prometheus - Loki stack)
- Nginx
- PostgreSQL
- Restic
- Sops
- SSL
- Tinyproxy
- VPN
- ZFS
Those blocks can be used with services not provided by SelfHostBlocks.
Some blocks 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.
Thanks to the blocks, SelfHostBlocks provides an unified configuration interface for the services it provides.
Compare the configuration for Nextcloud and Forgejo. 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.
shb.nextcloud = {
enable = true;
subdomain = "nextcloud";
domain = "example.com";
ssl = config.shb.certs.certs.letsencrypt.${domain};
apps.ldap = {
enable = true;
host = "127.0.0.1";
port = config.shb.ldap.ldapPort;
dcdomain = config.shb.ldap.dcdomain;
adminPassword.result = config.shb.sops.secrets."nextcloud/ldap/admin_password".result;
};
apps.sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
secret.result = config.shb.sops.secrets."nextcloud/sso/secret".result;
secretForAuthelia.result = config.shb.sops.secrets."nextcloud/sso/secretForAuthelia".result;
};
};shb.forgejo = {
enable = true;
subdomain = "forgejo";
domain = "example.com";
ssl = config.shb.certs.certs.letsencrypt.${domain};
ldap = {
enable = true;
host = "127.0.0.1";
port = config.shb.ldap.ldapPort;
dcdomain = config.shb.ldap.dcdomain;
adminPassword.result = config.shb.sops.secrets."nextcloud/ldap/admin_password".result;
};
sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
secret.result = config.shb.sops.secrets."forgejo/sso/secret".result;
secretForAuthelia.result = config.shb.sops.secrets."forgejo/sso/secretForAuthelia".result;
};
};As you can see, they are pretty similar! This makes setting up a new service pretty easy and intuitive.
SelfHostBlocks provides an ever growing list of services that are configured in the same way.
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, any reverse proxy you want or any database you want, without requiring work from maintainers of the services you want to self host.
A pre-RFC exists to upstream this concept into nixpkgs.
The manual also provides an explanation of the why and how of contracts.
Also, two videos exist of me presenting the topic, the first at NixCon North America in spring of 2024 and the second at NixCon in Berlin in fall of 2024.
Thanks to contracts, one can interface NixOS with systems on other OSes. The pre-RFC explains how that works.
By using SelfHostBlocks, you get all the benefits of NixOS which are, for self hosted applications specifically:
- declarative configuration;
- atomic configuration rollbacks;
- real programming language to define configurations;
- create your own higher level abstractions on top of SelfHostBlocks;
- integration with the rest of nixpkgs;
- much fewer "works on my machine" type of issues.
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:
RELEASE=0.2.4
nix flake update \
--override-input selfhostblocks github:ibizaman/selfhostblocks/$RELEASE \
selfhostblocksDemos that start and deploy a service on a Virtual Machine on your computer are located under the demo folder.
These show the onboarding experience you would get if you deployed one of the services on your own server.
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!
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.
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 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. 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.
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.
I was lucky to obtain a grant from NlNet which is an European fund, under NGI Zero Core, to work on this project. This also funds the contracts RFC.
Go apply for a grant too!
I'm following the Nextcloud license which is AGPLv3. See this article from the FSF that explains what this license adds to the GPL one.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
