{"id":14517523,"url":"https://github.com/ibizaman/selfhostblocks","last_synced_at":"2025-04-04T22:06:41.454Z","repository":{"id":148513447,"uuid":"579512254","full_name":"ibizaman/selfhostblocks","owner":"ibizaman","description":"Modular server management based on NixOS modules and focused on best practices.","archived":false,"fork":false,"pushed_at":"2024-10-29T17:29:12.000Z","size":3807,"stargazers_count":193,"open_issues_count":56,"forks_count":5,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-10-29T18:52:49.755Z","etag":null,"topics":["nix","nix-modules","self-hosted"],"latest_commit_sha":null,"homepage":"https://shb.skarabox.com","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ibizaman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-17T23:39:16.000Z","updated_at":"2024-10-29T17:29:15.000Z","dependencies_parsed_at":"2023-05-20T09:00:30.155Z","dependency_job_id":"341f0478-1d5b-4ec7-a02f-64aa54fada82","html_url":"https://github.com/ibizaman/selfhostblocks","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibizaman%2Fselfhostblocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibizaman%2Fselfhostblocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibizaman%2Fselfhostblocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ibizaman%2Fselfhostblocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ibizaman","download_url":"https://codeload.github.com/ibizaman/selfhostblocks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nix","nix-modules","self-hosted"],"created_at":"2024-09-04T03:01:17.860Z","updated_at":"2025-04-04T22:06:41.448Z","avatar_url":"https://github.com/ibizaman.png","language":"Nix","funding_links":[],"categories":["Software","NixOS Modules","Nix","Recently Updated"],"sub_categories":["Self-hosting Solutions","[Mar 01, 2025](/content/2025/03/01/README.md)","Zig"],"readme":"![GitHub Release](https://img.shields.io/github/v/release/ibizaman/selfhostblocks)\n![GitHub commits since latest release (branch)](https://img.shields.io/github/commits-since/ibizaman/selfhostblocks/latest/main)\n![GitHub commit activity (branch)](https://img.shields.io/github/commit-activity/w/ibizaman/selfhostblocks/main)\n![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr-raw/ibizaman/selfhostblocks)\n![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr-closed-raw/ibizaman/selfhostblocks?label=closed)\n![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-raw/ibizaman/selfhostblocks)\n![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-closed-raw/ibizaman/selfhostblocks?label=closed)\n\n[![Documentation](https://github.com/ibizaman/selfhostblocks/actions/workflows/pages.yml/badge.svg)](https://github.com/ibizaman/selfhostblocks/actions/workflows/pages.yml)\n[![Tests](https://github.com/ibizaman/selfhostblocks/actions/workflows/build.yaml/badge.svg)](https://github.com/ibizaman/selfhostblocks/actions/workflows/build.yaml)\n[![Demo](https://github.com/ibizaman/selfhostblocks/actions/workflows/demo.yml/badge.svg)](https://github.com/ibizaman/selfhostblocks/actions/workflows/demo.yml)\n![Matrix](https://img.shields.io/matrix/selfhostblocks%3Amatrix.org)\n\n\u003chr /\u003e\n\n# SelfHostBlocks\n\n*SelfHostBlocks is a NixOS based server management for self-hosting\nusing building blocks and promoting best practices.*\n\nIt is obvious by now that\na deep dependency on proprietary service providers - \"the cloud\" - is a significant liability.\nOne aspect often talked about is privacy which is inherently not guaranteed\nwhen using a proprietary service and is a valid concern.\nA more punishing issue is having your account closed or locked\nwithout prior warning.\nWhen that happens, you get an instantaneous sinking feeling in your stomach\nat the realization you lost access to your data, possibly without recourse.\n\nSelf-hosting is the only alternative that alleviate those concerns\nbut it requires a lot of technical skills and time.\nSelfHostBlocks' and its sibling project [Skarabox][]' goal\nis to lower the bar to self-hosting.\n\nSelfHostBlocks is different from other server management projects\nbecause it's main focus is ease of long term maintenance\nbefore ease of installation.\nTo achieve this, it provides building blocks to setup services.\nSome services are already provided out of the box\nand adding custom ones is done easily thanks to those blocks.\n\nThe building blocks fit nicely together thanks to [contracts](#contracts)\nwhich SelfHostBlocks introduces into nixpkgs.\nThis will increase modularity, code-reuse and empower end users to\nassemble components that fit together to build their server.\n\n## TOC\n\n\u003c!--toc:start--\u003e\n- [Usage](#usage)\n  - [Existing Installation](#existing-installation)\n  - [Installation From Scratch](#installation-from-scratch)\n  - [Full Example](#full-example)\n- [Features](#features)\n  - [Services](#services)\n  - [Blocks](#blocks)\n  - [Unified Interfaces](#unified-interfaces)\n  - [Contracts](#contracts)\n  - [Interfacing With Other OSes](#interfacing-with-other-oses)\n  - [Sitting on the Shoulders of a Giant](#sitting-on-the-shoulders-of-a-giant)\n  - [Automatic Updates](#automatic-updates)\n  - [Demos](#demos)\n- [Roadmap](#roadmap)\n- [Community](#community)\n- [Funding](#funding)\n- [License](#license)\n\u003c!--toc:end--\u003e\n\n## Usage\n\n\u003e **Caution:** You should know that although I am using everything in this repo for my personal\n\u003e production server, this is really just a one person effort for now and there are most certainly\n\u003e bugs that I didn't discover yet.\n\n### Existing Installation\n\nTo get started using SelfHostBlocks,\nfollow [the usage section](https://shb.skarabox.com/usage.html) of the manual.\nIt goes over how to deploy with [Colmena][], [nixos-rebuild][] and [deploy-rs][]\nand also goes over secrets management with [SOPS][].\n\n[Colmena]: https://shb.skarabox.com/usage.html#usage-example-colmena\n[nixos-rebuild]: https://shb.skarabox.com/usage.html#usage-example-nixosrebuild\n[deploy-rs]: https://shb.skarabox.com/usage.html#usage-example-deployrs\n[SOPS]: https://shb.skarabox.com/usage.html#usage-secrets\n\nThen, to actually configure services, you can choose which one interests you in\n[the services section](https://shb.skarabox.com/services.html) of the manual.\nNot all services have a corresponding manual page yet.\n\nHead over to the [matrix channel](https://matrix.to/#/#selfhostblocks:matrix.org)\nfor any remaining question, or just to say hi :)\n\n### Installation From Scratch\n\nI do recommend for this my sibling project [Skarabox][]\nwhich bootstraps a new server and sets up a few tools:\n\n- Create a bootable ISO, installable on an USB key.\n- Handles one or two (in raid 1) SSDs for root partition.\n- Handles two (in raid 1) or more hard drives for data partition.\n- [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to install NixOS headlessly.\n- [disko](https://github.com/nix-community/disko) to format the drives using native ZFS encryption with remote unlocking through ssh.\n- [sops-nix](https://github.com/Mic92/sops-nix) to handle secrets.\n- [deploy-rs](https://github.com/serokell/deploy-rs) to deploy updates.\n\n[Skarabox]:  https://github.com/ibizaman/skarabox\n\n### Full Example\n\nSee [full example][] in the manual.\n\n[full example]: https://shb.skarabox.com/usage.html#usage-complete-example\n\n## Features\n\nSelfHostBlocks provides building blocks that take care of common self-hosting needs:\n\n- Backup for all services.\n- Automatic creation of ZFS datasets per service.\n- LDAP and SSO integration for most services.\n- Monitoring with Grafana and Prometheus stack with provided dashboards.\n- Automatic reverse proxy and certificate management for HTTPS.\n- VPN and proxy tunneling services.\n\nGreat care is taken to make the proposed stack robust.\nThis translates into a test suite comprised of automated NixOS VM tests\nwhich includes playwright tests to verify some important workflow\nlike logging in.\n\nAlso, the stack fits together nicely thanks to [contracts](#contracts).\n\n### Services\n\n[Provided services](https://shb.skarabox.com/services.html) are:\n\n- Nextcloud\n- Audiobookshelf\n- Deluge + *arr stack\n- Forgejo\n- Grocy\n- Hledger\n- Home-Assistant\n- Jellyfin\n- Nextcloud\n- Vaultwarden\n\nLike explained above, those services all benefit from\nout of the box backup,\nLDAP and SSO integration,\nmonitoring with Grafana,\nreverse proxy and certificate management\nand VPN integration for the *arr suite.\n\nSome services do not have an entry yet in the manual.\nTo know options for those, the only way for now\nis to go to the [All Options][] section of the manual.\n\n[All Options]: https://shb.skarabox.com/options.html\n\n### Blocks\n\nThe services above rely on the following [common blocks][]:\n\n[common blocks]: https://shb.skarabox.com/blocks.html\n\n- Authelia\n- BorgBackup\n- Davfs\n- LDAP\n- Monitoring (Grafana - Prometheus - Loki stack)\n- Nginx\n- PostgreSQL\n- Restic\n- Sops\n- SSL\n- Tinyproxy\n- VPN\n- ZFS\n\nThose blocks can be used with services\nnot provided by SelfHostBlocks.\n\nSome blocks do not have an entry yet in the manual.\nTo know options for those, the only way for now\nis to go to the [All Options][] section of the manual.\n\n### Unified Interfaces\n\nThanks to the blocks,\nSelfHostBlocks provides an unified configuration interface\nfor the services it provides.\n\nCompare the configuration for Nextcloud and Forgejo.\nThe following snippets focus on similitudes and assume the relevant blocks - like secrets - are configured off-screen.\nIt also does not show specific options for each service.\nThese are still complete snippets that configure HTTPS,\nsubdomain serving the service, LDAP and SSO integration.\n\n```nix\nshb.nextcloud = {\n  enable = true;\n  subdomain = \"nextcloud\";\n  domain = \"example.com\";\n\n  ssl = config.shb.certs.certs.letsencrypt.${domain};\n\n  apps.ldap = {\n    enable = true;\n    host = \"127.0.0.1\";\n    port = config.shb.ldap.ldapPort;\n    dcdomain = config.shb.ldap.dcdomain;\n    adminPassword.result = config.shb.sops.secrets.\"nextcloud/ldap/admin_password\".result;\n  };\n  apps.sso = {\n    enable = true;\n    endpoint = \"https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}\";\n\n    secret.result = config.shb.sops.secrets.\"nextcloud/sso/secret\".result;\n    secretForAuthelia.result = config.shb.sops.secrets.\"nextcloud/sso/secretForAuthelia\".result;\n  };\n};\n```\n\n```nix\nshb.forgejo = {\n  enable = true;\n  subdomain = \"forgejo\";\n  domain = \"example.com\";\n\n  ssl = config.shb.certs.certs.letsencrypt.${domain};\n\n  ldap = {\n    enable = true;\n    host = \"127.0.0.1\";\n    port = config.shb.ldap.ldapPort;\n    dcdomain = config.shb.ldap.dcdomain;\n    adminPassword.result = config.shb.sops.secrets.\"nextcloud/ldap/admin_password\".result;\n  };\n\n  sso = {\n    enable = true;\n    endpoint = \"https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}\";\n\n    secret.result = config.shb.sops.secrets.\"forgejo/sso/secret\".result;\n    secretForAuthelia.result = config.shb.sops.secrets.\"forgejo/sso/secretForAuthelia\".result;\n  };\n};\n```\n\nAs you can see, they are pretty similar!\nThis makes setting up a new service pretty easy and intuitive.\n\nSelfHostBlocks provides an ever growing list of [services](#provided-services)\nthat are configured in the same way.\n\n### Contracts\n\nTo make building blocks that fit nicely together,\nSelfHostBlocks pioneers [contracts][] which allows you, the final user,\nto be more in control of which piece goes where.\nThis lets you choose, for example,\nany reverse proxy you want or any database you want,\nwithout requiring work from maintainers of the services you want to self host.\n\nA [pre-RFC][] exists to upstream this concept into `nixpkgs`.\nThe [manual][contracts] also provides an explanation of the why and how of contracts.\n\nAlso, two videos exist of me presenting the topic,\nthe first at [NixCon North America in spring of 2024][NixConNA2024]\nand the second at [NixCon in Berlin in fall of 2024][NixConBerlin2024].\n\n[contracts]: https://shb.skarabox.com/contracts.html\n[pre-RFC]: https://discourse.nixos.org/t/pre-rfc-decouple-services-using-structured-typing/58257\n[NixConNA2024]: https://www.youtube.com/watch?v=lw7PgphB9qM\n[NixConBerlin2024]: https://www.youtube.com/watch?v=CP0hR6w1csc\n\n### Interfacing With Other OSes\n\nThanks to [contracts](#contracts), one can interface NixOS\nwith systems on other OSes.\nThe [pre-RFC][] explains how that works.\n\n### Sitting on the Shoulders of a Giant\n\nBy using SelfHostBlocks, you get all the benefits of NixOS\nwhich are, for self hosted applications specifically:\n\n- declarative configuration;\n- atomic configuration rollbacks;\n- real programming language to define configurations;\n- create your own higher level abstractions on top of SelfHostBlocks;\n- integration with the rest of nixpkgs;\n- much fewer \"works on my machine\" type of issues.\n\n### Automatic Updates\n\nSelfHostBlocks follows nixpkgs unstable branch closely.\nThere is a GitHub action running every couple of days that updates\nthe `nixpkgs` input in the root `flakes.nix`,\nruns the tests and merges the PR automatically\nif the tests pass.\n\nA release is then made every few commits,\nwhenever deemed sensible.\nOn your side, to update I recommend pinning to a release\nwith the following command,\nreplacing the RELEASE with the one you want:\n\n```bash\nRELEASE=0.2.4\nnix flake update \\\n  --override-input selfhostblocks github:ibizaman/selfhostblocks/$RELEASE \\\n  selfhostblock\n```\n\n### Demos\n\nDemos that start and deploy a service\non a Virtual Machine on your computer are located\nunder the [demo](./demo/) folder.\n\nThese show the onboarding experience you would get\nif you deployed one of the services on your own server.\n\n## Roadmap\n\nCurrently, the Nextcloud and Vaultwarden services\nand the SSL and backup blocks\nare the most advanced and most documented.\n\nDocumenting all services and blocks will be done\nas I make all blocks and services use the contracts.\n\nUpstreaming changes is also on the roadmap.\n\nCheck the [issues][] and the [milestones]() to see planned work.\nFeel free to add more or to contribute!\n\n[issues]: (https://github.com/ibizaman/selfhostblocks/issues)\n[milestones]: https://github.com/ibizaman/selfhostblocks/milestones\n\nAll blocks and services have NixOS tests.\nAlso, I am personally using all the blocks and services in this project, so they do work to some extent.\n\n## Community\n\nThis project has been the main focus\nof my (non work) life for the past 3 year now\nand I intend to continue working on this for a long time.\n\nAll issues and PRs are welcome. For PRs, if they are substantial changes, please open an issue to\ndiscuss the details first. More details in [the contributing section](https://shb.skarabox.com/contributing.html)\nof the manual.\n\nCome hang out in the [Matrix channel](https://matrix.to/#/%23selfhostblocks%3Amatrix.org). :)\n\nOne aspect that's close to my heart is I intent to make SelfHostBlocks the lightest layer on top of nixpkgs as\npossible. I want to upstream as much as possible. I will still take some time to experiment here but\nwhen I'm satisfied with how things look, I'll upstream changes.\n\n## Funding\n\nI was lucky to [obtain a grant][nlnet] from NlNet which is an European fund,\nunder [NGI Zero Core][NGI0],\nto work on this project.\nThis also funds the contracts RFC.\n\nGo apply for a grant too!\n\n[nlnet]: https://nlnet.nl/project/SelfHostBlocks\n[NGI0]: https://nlnet.nl/core/\n\n\u003cp\u003e\n\u003cimg alt=\"NlNet logo\" src=\"https://nlnet.nl/logo/banner.svg\" width=\"200\" /\u003e\n\u003cimg alt=\"NGI Zero Core logo\" src=\"https://nlnet.nl/image/logos/NGI0Core_tag.svg\" width=\"200\" /\u003e\n\u003c/p\u003e\n\n## License\n\nI'm following the [Nextcloud](https://github.com/nextcloud/server) license which is AGPLv3.\nSee [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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibizaman%2Fselfhostblocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fibizaman%2Fselfhostblocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fibizaman%2Fselfhostblocks/lists"}