hosting/selfhostblocks
1
0
Fork 0
Code Issues Activity

update readme

Browse source
This commit is contained in:
ibizaman 2024-09-18 08:00:30 +02:00
parent a1c4d5f141
commit d7136b52e5
2 changed files with 191 additions and 44 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

129
README.md
View file

@ -6,25 +6,16 @@
[![Tests](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fibizaman%2Fselfhostblocks%3Fbranch%3Dmain)](https://garnix.io) (using Garnix) [![Tests](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fibizaman%2Fselfhostblocks%3Fbranch%3Dmain)](https://garnix.io) (using Garnix)
[![Demo](https://github.com/ibizaman/selfhostblocks/actions/workflows/demo.yml/badge.svg)](https://github.com/ibizaman/selfhostblocks/actions/workflows/demo.yml) [![Demo](https://github.com/ibizaman/selfhostblocks/actions/workflows/demo.yml/badge.svg)](https://github.com/ibizaman/selfhostblocks/actions/workflows/demo.yml)
SHB's (Self Host Blocks) is yet another server management tool whose goal is to provide better SHB (Self Host Blocks) is yet another server management tool
building blocks for self-hosting. Indeed, SHB provides opinionated [building that is not like the other server management tools.
blocks](#available-blocks) fitting together to self-host any service you'd want. Some [common
services](#provided-services) are provided out of the box.
SHB's goal is to make these building blocks plug-and-play. To achieve this, SHB pioneers
[contracts](https://shb.skarabox.com/contracts.html) which allows you, the final user, to be more in
control of which pieces go where. The promise here is to let 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.
To achieve all this, SHB is using the full power of NixOS modules and NixOS VM tests. Indeed, each
building block and each service is a NixOS module using modules defined in
[Nixpkgs](https://github.com/NixOS/nixpkgs/) and they are tested using full VMs on every commit.
## TOC ## TOC
<!--toc:start--> <!--toc:start-->
- [Unified Interfaces](#unified-interfaces)
- [Incremental Adoption](#incremental-adoption)
- [Usage](#usage) - [Usage](#usage)
- [More Benefits of SHB](#more-benefits-of-shb)
- [Manual](#manual) - [Manual](#manual)
- [Roadmap](#roadmap) - [Roadmap](#roadmap)
- [Available Blocks](#available-blocks) - [Available Blocks](#available-blocks)
@ -34,35 +25,117 @@ building block and each service is a NixOS module using modules defined in
- [License](#license) - [License](#license)
<!--toc:end--> <!--toc:end-->
## Unified Interfaces
SHB's first goal is to provide unified [building blocks](#available-blocks)
and by extension configuration interface, for self-hosting.
Compare the configuration for Nextcloud and Forgejo in Self Host Blocks.
The following snippets focus on similitudes and assume the relevant blocks 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
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;
adminPasswordFile = config.sops.secrets."nextcloud/ldap_admin_password".path;
};
apps.sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
secretFile = config.sops.secrets."nextcloud/sso/secret".path;
secretFileForAuthelia = config.sops.secrets."authelia/nextcloud_sso_secret".path;
};
};
```
```nix
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;
adminPasswordFile = config.sops.secrets."forgejo/ldap_admin_password".path;
};
sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
secretFile = config.sops.secrets."forgejo/ssoSecret".path;
secretFileForAuthelia = config.sops.secrets."forgejo/authelia/ssoSecret".path;
};
};
```
As you can see, they are pretty similar!
SHB provides an ever growing list of [services](#provided-services)
that are configured in the same way.
## Incremental Adoption
SHB's second goal is to facilitate testing NixOS
and slowly switching an existing installation to NixOS.
To achieve this, SHB pioneers [contracts][]
which allows you, the final user, to be more in control of which piece go 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.
(See [manual][contracts] for a complete explanation)
[contracts]: https://shb.skarabox.com/contracts.html
## Usage ## Usage
> **Caution:** You should know that although I am using everything in this repo for my personal > **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 > production server, this is really just a one person effort for now and there are most certainly
> bugs that I didn't discover yet. > bugs that I didn't discover yet.
Self Host Blocks is available as a flake. To use it in your project, add the following flake input: Self Host Blocks is available as a flake.
To use it in your project, add the following flake input:
```nix ```nix
inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks"; inputs.selfhostblocks.url = "github:ibizaman/selfhostblocks";
``` ```
This is not quite enough though and more information is provided in [the More information is provided in [the manual](https://shb.skarabox.com/usage.html),
manual](https://shb.skarabox.com/usage.html). like secrets management.
- You are new to self hosting and want pre-configured services to deploy easily. Look at the - You are new to self hosting and want pre-configured services to deploy easily.
[services section](https://shb.skarabox.com/services.html). Look at the [services section](https://shb.skarabox.com/services.html).
- You are a seasoned self-hoster but want to enhance some services you deploy already. Go to the - You are a seasoned self-hoster but want to enhance some services you deploy already.
[blocks section](https://shb.skarabox.com/blocks.html). Go to the [blocks section](https://shb.skarabox.com/blocks.html).
- You are a user of Self Host Blocks but would like to use your own implementation for a block. Go - You are a user of Self Host Blocks but would like to use your own implementation for a block.
to the [contracts section](https://shb.skarabox.com/contracts.html). Go to the [contracts section](https://shb.skarabox.com/contracts.html).
Head over to the [matrix channel](https://matrix.to/#/#selfhostblocks:matrix.org) for any remaining Head over to the [matrix channel](https://matrix.to/#/#selfhostblocks:matrix.org)
question, or just to say hi :) for any remaining question, or just to say hi :)
## Why yet another self hosting tool? ## More Benefits of SHB
By using Self Host Blocks, you get all the benefits of NixOS which are, for self hosted applications By using Self Host Blocks, you get all the benefits of NixOS
specifically: which are, for self hosted applications specifically:
- declarative configuration; - declarative configuration;
- atomic configuration rollbacks; - atomic configuration rollbacks;

106
docs/preface.md
View file

@ -1,28 +1,102 @@
# Preface {#preface} # Preface {#preface}
::: {.note} ::: {.note}
Self Host Blocks is hosted on [GitHub](https://github.com/ibizaman/selfhostblocks). If you encounter Self Host Blocks is hosted on [GitHub](https://github.com/ibizaman/selfhostblocks).
problems or bugs then please report them on the [issue If you encounter problems or bugs then please report them on the [issue
tracker](https://github.com/ibizaman/selfhostblocks/issues). tracker](https://github.com/ibizaman/selfhostblocks/issues).
Feel free to join the dedicated Matrix room 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 with best practices out of Self Host Blocks intends to help you self host any service you would like
the box. with best practices out of the box.
To achieve this, Self Host Blocks provides building blocks which each provide part of what a self Compared to the stock nixpkgs experience, Self Host Blocks provides
hosted app should do (SSO, HTTPS, etc.). It also provides some services that are already integrated an unified interface to setup common dependencies, called blocks
with all those building blocks. in this project:
- You are new to self hosting and want pre-configured services to deploy easily. Look at the - reverse proxy
[services section](services.html). - TLS certificate management
- You are a seasoned self-hoster but want to enhance some services you deploy already. Go to the - serving service under subdomain
[blocks section](blocks.html). - backup
- You are a user of Self Host Blocks but would like to use your own implementation for a block. Head - LDAP
over to the [matrix channel](https://matrix.to/#/#selfhostblocks:matrix.org) (the manual for this - SSO.
is WIP).
Self Host Blocks uses the full power of NixOS modules to achieve these goals. Blocks and service are Compare the configuration for Nextcloud and Forgejo.
both NixOS modules. The following snippets focus on similitudes and assume the relevant blocks are configured off-screen.
```nix
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;
adminPasswordFile = config.sops.secrets."nextcloud/ldap_admin_password".path;
};
apps.sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
secretFile = config.sops.secrets."nextcloud/sso/secret".path;
secretFileForAuthelia = config.sops.secrets."authelia/nextcloud_sso_secret".path;
};
};
```
```nix
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;
adminPasswordFile = config.sops.secrets."forgejo/ldap_admin_password".path;
};
sso = {
enable = true;
endpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
secretFile = config.sops.secrets."forgejo/ssoSecret".path;
secretFileForAuthelia = config.sops.secrets."forgejo/authelia/ssoSecret".path;
};
};
```
SHB facilitates testing NixOS and slowly switching an existing installation to NixOS.
To achieve this, SHB pioneers [contracts][]
which allows you, the final user, to be more in control of which piece go 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.
[contracts]: contracts.html
To achieve this, Self Host Blocks provides building blocks
which each provide part of what a self hosted app should do (SSO, HTTPS, etc.).
It also provides some services that are already integrated with all those building blocks.
- You are new to self hosting and want pre-configured services to deploy easily.
Look at the [services section](services.html).
- You are a seasoned self-hoster but want to enhance some services you deploy already.
Go to the [blocks section](blocks.html).
- You are a user of Self Host Blocks but would like to use your own implementation for a block.
Go to the [contracts section](https://shb.skarabox.com/contracts.html).
Self Host Blocks uses the full power of NixOS modules to achieve these goals.
Blocks and service are both NixOS modules.