1
0
Fork 0

more docs

This commit is contained in:
ibizaman 2024-02-02 12:16:38 -08:00 committed by Pierre Penninckx
parent b1343d7f86
commit 11728af05f
4 changed files with 37 additions and 16 deletions

View file

@ -62,16 +62,22 @@ specifically:
- user-defined abstractions (create your own functions or NixOS modules on top of SHB!); - user-defined abstractions (create your own functions or NixOS modules on top of SHB!);
- integration with the rest of nixpkgs. - integration with the rest of nixpkgs.
Also, SHB intends to be a library, not a framework, so you can make it fit in your existing In no particular order, here are some aspects of SHB which I find interesting and differentiates it
deployment, slowly transitioning to using SHB one block or service at a time. from other server management projects:
Each [building block](#available-blocks) defines a part of what a self-hosted app should provide. - SHB intends to be a library, not a framework. You can either go all in and use SHB provided
For example, HTTPS access through a subdomain or Single Sign-On. The goal of SHB is to make sure services directly or use just one block in your existing infrastructure.
those blocks all fit together, whatever the actual implementation you choose. For example, the - SHB introduces contracts to allow you to swap implementation for each self-hosting need.
subdomain access could be done using Caddy or Nginx. This is achieved by providing an explicit For example, you should be able to use the reverse proxy you want without modifying any services
contract for each block like for the [SSL depending on it.
block](https://shb.skarabox.com/blocks-ssl.html#ssl-block-contract) and validating that contract - SHB contracts also allows you to use your own custom implementation instead of the provided one,
using NixOS VM integration tests. as long as it follows the contract and passes the tests.
- SHB provides at least one implementation for each self-hosting need like backups, SSL
certificates, reverse proxy, VPN, etc. Those are called blocks here. They are documented in [the
manual](https://shb.skarabox.com/blocks.html).
- SHB follows nixpkgs unstable branch closely. There is a GitHub action running daily that updates
the `nixpkgs` input in the root `flakes.nix`, runs the tests and merges a PR with the new input if
the tests pass.
## Manual ## Manual
@ -125,14 +131,13 @@ the services on your own server.
## Community ## Community
All issues and PRs are welcome. For PRs, if they are substantial changes, please open an issue to All issues and PRs are welcome. For PRs, if they are substantial changes, please open an issue to
discuss the details first. discuss the details first. More details in [here](https://shb.skarabox.com/contributing.html).
Come hang out in the [Matrix channel](https://matrix.to/#/%23selfhostblocks%3Amatrix.org). :) Come hang out in the [Matrix channel](https://matrix.to/#/%23selfhostblocks%3Amatrix.org). :)
One important goal of SHB is to be the smallest amount of code above what is available in One aspect that's close to my heart is I intent to make SHB the lightest layer on top of nixpkgs as
[nixpkgs](https://github.com/NixOS/nixpkgs). It should be the minimum necessary to make packages possible. I want to upstream as much as possible. I will still take some time to experiment here but
available there conform with the contracts. This way, there are less chance of breakage when nixpkgs when I'm satisfied with how things look, I'll upstream changes.
gets updated. I intend to upstream to nixpkgs as much of those as makes sense.
## License ## License

View file

@ -26,6 +26,10 @@ Self Host Blocks provides at least one implementation for each block and allows
implementation if you want to, as long as it passes the tests. You can then use blocks to improve implementation if you want to, as long as it passes the tests. You can then use blocks to improve
services you already have deployed. services you already have deployed.
::: {.note}
Not all blocks are yet documented. You can find all available blocks [in the repository](@REPO@/modules/blocks).
:::
```{=include=} chapters html:into-file=//blocks-ssl.html ```{=include=} chapters html:into-file=//blocks-ssl.html
modules/blocks/ssl/docs/default.md modules/blocks/ssl/docs/default.md
``` ```

View file

@ -11,8 +11,10 @@ Come hang out in the [Matrix channel](https://matrix.to/#/%23selfhostblocks%3Ama
## Upstream Changes {#contributing-upstream} ## Upstream Changes {#contributing-upstream}
Along the way, I made quite a few changes to the ubderlying nixpkgs module I'm using. I intend to One important goal of SHB is to be the smallest amount of code above what is available in
upstream to nixpkgs as much of those as makes sense. [nixpkgs](https://github.com/NixOS/nixpkgs). It should be the minimum necessary to make packages
available there conform with the contracts. This way, there are less chance of breakage when nixpkgs
gets updated. I intend to upstream to nixpkgs as much of those as makes sense.
## Run tests {#contributing-runtests} ## Run tests {#contributing-runtests}

View file

@ -1,5 +1,15 @@
# Services {#services} # Services {#services}
Services are usually web applications that SHB help you self-host. Configuration of those is
purposely made opinionated and require as few nix options as can make sense. That is possible thanks to the extensive use of blocks provided by SHB.
::: {.note}
Not all services are yet documented. You can find all available services [in the repository](@REPO@/modules/services).
:::
The following table summarizes for each documented service what features it provides. More
information is provided in the respective manual sections.
| Service | Backup | Reverse Proxy | SSO | LDAP | Monitoring | Profiling | | Service | Backup | Reverse Proxy | SSO | LDAP | Monitoring | Profiling |
|-----------------------|--------|---------------|-----|-------|------------|-----------| |-----------------------|--------|---------------|-----|-------|------------|-----------|
| [Nextcloud Server][1] | P (1) | Y | Y | Y | Y | P (2) | | [Nextcloud Server][1] | P (1) | Y | Y | Y | Y | P (2) |