The service catalog

Services are the self-hosted building blocks of the network. They are enabled per host, in etc/config.yaml. The host profile does not matter.

Enabling a service

Under a host’s services key, each entry enables a service. The (optional) value customizes it:

etc/config.yaml

    services:
      immich:
        title: "Photos"
        description: "My photos & videos"
        domain: "photos"          # service subdomain
        global: true              # → https://photos.domain.tld (public, no zone)
      nextcloud:
        domain: "cloud"           # → cloud.<zone>.domain.tld (not global)
      restic:                     # default values

Field	Role
(key)	The service to enable (e.g. immich)
title	Name displayed on the portal
description	Subtitle on the portal
domain	Subdomain (default: service name). FQDN: <domain>.<zone>.domain.tld
global	Exposes publicly via HCS: <domain>.domain.tld, without the zone (public DNS)
icon	Portal icon

Visible across the whole network

Declaring a service in etc/config.yaml makes it visible and resolvable from all zones. See Names and DNS resolution.

Joining a zone service from outside

A zone service (not global) keeps its zone URL <domain>.<zone>.domain.tld and normally only responds on the LAN, other zones and the tailnet. Some services are additionally marked externalAccess in the framework registry (dnf/config/modules.nix) : the HCS then publishes them to the outside while keeping the zone URL.

Routing : internet → public DNS → HCS → (tailnet) → zone gateway → backend. The HCS terminates the public TLS certificate and relays the request to the zone gateway, whose own vhost handles SSO and the backend. Internal resolution is unchanged (direct to host/gateway).

Exposing a service…	Flag	Result
Publicly, entire network	global: true (per service, config.yaml)	<domain>.domain.tld, no zone, served by the HCS
Publicly, keeping the zone URL	externalAccess (registry)	<domain>.<zone>.domain.tld, fronted by the HCS

Two prerequisites

• Public DNS : <domain>.<zone>.domain.tld (or the wildcard *.<zone>.domain.tld) must resolve to the HCS public IP at your registrar — the HCS also needs this to obtain the ACME certificate.
• A service marked proxy.isInternal (LAN only, e.g. adguardhome, searx) cannot be externalAccess : the build fails on an assertion.

The catalogue

Category	Services
Authentication	idm (Kanidm), vaultwarden
Files & cloud	nextcloud, oxicloud, immich, garage, minio, nfs
Communication	matrix, matrix-admin, element, jitsi-meet, turn
Media & leisure	jellyfin, mealie, geneweb, stk
Productivity	outline, docs, searx
AI	ai (Open WebUI + Ollama)
Network	dnsmasq, adguardhome, headscale, tailscale, homepage
Development	forgejo, harmonia, nix-cache
Monitoring & backup	monitoring, loki, restic
System	fail2ban, postfix, printing, audio, home-assistant

Full reference

Detailed options for each service in the module reference.

Portal and access

• Portal: the homepage service provides a services dashboard, per zone.
• Single sign-on: most services go through SSO Kanidm.
• Local or global: a service stays in its zone, unless global: true exposes it publicly.

Services with a pinned version

Some services cannot follow nixpkgs’ default version: their upstream forbids skipping a major version. DNF therefore pins the package in the module, and upgrades happen one major version at a time.

Service	Option	Upstream constraint
idm (Kanidm)	services.kanidm.package	A single maintained version, end of life 30 days after the next release
nextcloud	services.nextcloud.package	34 → 35 possible, 33 → 35 impossible

Check the running version before upgrading

Pinning the next major version while the instance is not yet ready for it makes the migration fail at boot. Query the service itself first: kanidmd domain upgrade-check for Kanidm, nextcloud-occ status for Nextcloud.

The signal that an upgrade must be planned is a warning at evaluation time, emitted as soon as the pinned version is deprecated. Kanidm’s detailed procedure, which can be applied to the other services, is described at the end of the page SSO and identities.

Back up before upgrading

These migrations rewrite the database schema at the first startup of the new version, with no rollback. The prior backup is not a comfort precaution.

Kanidm stores in SQLite, so service stopped :

sudo systemctl stop kanidm
sudo install -d -o kanidm -g kanidm /var/lib/kanidm/pre-upgrade
sudo cp -a /var/lib/kanidm/kanidm.db* /var/lib/kanidm/pre-upgrade/
sudo kanidmd database backup /var/lib/kanidm/pre-upgrade/dump.json -c /etc/kanidm/server.toml
sudo chown -R kanidm:kanidm /var/lib/kanidm
sudo systemctl start kanidm

The * is essential : the write-ahead log kanidm.db-wal survives the service shutdown and carries the latest transactions.

Nextcloud stores in PostgreSQL, so without interruption : pg_dump -Fc takes a consistent transactional snapshot on a live database.

sudo install -d -o nextcloud -g nextcloud -m 0750 /var/lib/nextcloud/pre-upgrade
sudo -u postgres pg_dump -Fc nextcloud > /var/lib/nextcloud/pre-upgrade/nextcloud.dump
sudo cp -a /var/lib/nextcloud/config/config.php /var/lib/nextcloud/pre-upgrade/
sudo chown -R nextcloud:nextcloud /var/lib/nextcloud/pre-upgrade

Do not omit config.php : it carries the installed version number, without which a restored database does not restart.

Re-read the dump before deploying

An unreadable dump is never discovered at the right time. pg_restore -l lists its content without restoring anything :

sudo -u nextcloud pg_restore -l /var/lib/nextcloud/pre-upgrade/nextcloud.dump | wc -l