selfhostblocks/docs/preface.md

Preface

::: {.note} Self Host Blocks is hosted on GitHub. If you encounter problems or bugs then please report them on the issue tracker.

Feel free to join the dedicated Matrix room matrix.org#selfhostblocks. :::

Self Host Blocks intends to help you self host any service you would like with best practices out of the box.

Compared to the stock nixpkgs experience, Self Host Blocks provides an unified interface to setup common dependencies, called blocks in this project:

• reverse proxy
• TLS certificate management
• serving service under subdomain
• backup
• LDAP
• SSO.

Compare the configuration for Nextcloud and Forgejo. The following snippets focus on similitudes and assume the relevant blocks are configured off-screen.

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;
  };
};

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.

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.
• You are a seasoned self-hoster but want to enhance some services you deploy already. Go to the blocks section.
• You are a user of Self Host Blocks but would like to use your own implementation for a block. Go to the contracts section.

Self Host Blocks uses the full power of NixOS modules to achieve these goals. Blocks and service are both NixOS modules.