Skip to content

Commit

Permalink
more docs
Browse files Browse the repository at this point in the history
  • Loading branch information
ibizaman committed Feb 2, 2024
1 parent b1343d7 commit 11728af
Show file tree
Hide file tree
Showing 4 changed files with 38 additions and 17 deletions.
35 changes: 20 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,16 +62,22 @@ specifically:
- user-defined abstractions (create your own functions or NixOS modules on top of SHB!);
- 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
deployment, slowly transitioning to using SHB one block or service at a time.

Each [building block](#available-blocks) defines a part of what a self-hosted app should provide.
For example, HTTPS access through a subdomain or Single Sign-On. The goal of SHB is to make sure
those blocks all fit together, whatever the actual implementation you choose. For example, the
subdomain access could be done using Caddy or Nginx. This is achieved by providing an explicit
contract for each block like for the [SSL
block](https://shb.skarabox.com/blocks-ssl.html#ssl-block-contract) and validating that contract
using NixOS VM integration tests.
In no particular order, here are some aspects of SHB which I find interesting and differentiates it
from other server management projects:

- SHB intends to be a library, not a framework. You can either go all in and use SHB provided
services directly or use just one block in your existing infrastructure.
- SHB introduces contracts to allow you to swap implementation for each self-hosting need.
For example, you should be able to use the reverse proxy you want without modifying any services
depending on it.
- SHB contracts also allows you to use your own custom implementation instead of the provided one,
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

Expand Down Expand Up @@ -125,14 +131,13 @@ the services on your own server.
## Community

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

One important goal of SHB is to be the smallest amount of code above what is available in
[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.
One aspect that's close to my heart is I intent to make SHB 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.

## License

Expand Down
4 changes: 4 additions & 0 deletions docs/blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
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
modules/blocks/ssl/docs/default.md
```
Expand Down
6 changes: 4 additions & 2 deletions docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ Come hang out in the [Matrix channel](https://matrix.to/#/%23selfhostblocks%3Ama

## Upstream Changes {#contributing-upstream}

Along the way, I made quite a few changes to the ubderlying nixpkgs module I'm using. I intend to
upstream to nixpkgs as much of those as makes sense.
One important goal of SHB is to be the smallest amount of code above what is available in
[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}

Expand Down
10 changes: 10 additions & 0 deletions docs/services.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# 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 |
|-----------------------|--------|---------------|-----|-------|------------|-----------|
| [Nextcloud Server][1] | P (1) | Y | Y | Y | Y | P (2) |
Expand Down

0 comments on commit 11728af

Please sign in to comment.