Le catalogue de services

Les services sont les briques auto-hébergées du réseau. On les active par hôte, dans etc/config.yaml. Le profil de l’hôte n’a pas d’importance.

Activer un service

Sous la clé services d’un hôte, chaque entrée active un service. La valeur (facultative) le personnalise :

etc/config.yaml

    services:
      immich:
        title: "Photos"
        description: "Mes photos & vidéos"
        domain: "photos"          # sous-domaine du service
        global: true              # → https://photos.domain.tld (public, sans zone)
      nextcloud:
        domain: "cloud"           # → cloud.<zone>.domain.tld (non global)
      restic:                     # valeurs par défaut

Champ	Rôle
(clé)	Le service à activer (ex. immich)
title	Nom affiché sur le portail
description	Sous-titre sur le portail
domain	Sous-domaine (défaut : nom du service). FQDN : <domain>.<zone>.domain.tld
global	Expose publiquement via le HCS : <domain>.domain.tld, sans la zone (DNS public)
icon	Icône du portail

Visible sur tout le réseau

Déclarer un service dans etc/config.yaml le rend visible et résolvable depuis toutes les zones. Voir Noms et résolution DNS.

Joindre un service de zone depuis l’extérieur

Un service de zone (non global) garde son URL de zone <domain>.<zone>.domain.tld et ne répond normalement que sur le LAN, les autres zones et le tailnet. Certains services sont en plus marqués externalAccess dans le registre du framework (dnf/config/modules.nix) : le HCS les publie alors vers l’extérieur tout en conservant l’URL de zone.

Routage : internet → DNS public → HCS → (tailnet) → passerelle de zone → backend. Le HCS termine le certificat TLS public et relaie la requête vers la passerelle de zone, dont le propre vhost gère le SSO et le backend. La résolution interne est inchangée (directe vers l’hôte/la passerelle).

Exposer un service…	Drapeau	Résultat
Publiquement, tout le réseau	global: true (par service, config.yaml)	<domain>.domain.tld, sans zone, servi par le HCS
Publiquement, en gardant l’URL de zone	externalAccess (registre)	<domain>.<zone>.domain.tld, fronté par le HCS

Deux pré-requis

• DNS public : <domain>.<zone>.domain.tld (ou le joker *.<zone>.domain.tld) doit résoudre vers l’IP publique du HCS chez votre registrar — le HCS en a aussi besoin pour obtenir le certificat ACME.
• Un service marqué proxy.isInternal (LAN uniquement, ex. adguardhome, searx) ne peut pas être externalAccess : le build échoue sur une assertion.

Le catalogue

Catégorie	Services
Authentification	idm (Kanidm), vaultwarden
Fichiers & cloud	nextcloud, oxicloud, immich, garage, minio, nfs
Communication	matrix, element, jitsi-meet, turn
Médias & loisirs	jellyfin, mealie, geneweb
Productivité	outline, docs, searx
IA	ai (Open WebUI + Ollama)
Réseau	dnsmasq, adguardhome, headscale, tailscale, homepage
Développement	forgejo, harmonia, nix-cache
Supervision & sauvegarde	monitoring, loki, restic
Système	fail2ban, postfix, printing, audio, home-assistant

Référence complète

Options détaillées de chaque service dans la référence des modules.

Portail et accès

• Portail : le service homepage dresse une page d’accueil des services, par zone.
• Authentification unique : la plupart des services passent par le SSO Kanidm.
• Local ou global : un service reste dans sa zone, sauf global: true qui l’expose publiquement.

Services à version épinglée

Quelques services ne peuvent pas suivre la version par défaut de nixpkgs : leur éditeur interdit de sauter une version majeure. DNF épingle donc le paquet dans le module, et la montée se fait une majeure à la fois.

Service	Option	Contrainte amont
idm (Kanidm)	services.kanidm.package	Une seule version maintenue, fin de vie 30 jours après la sortie de la suivante
nextcloud	services.nextcloud.package	33 → 34 possible, 33 → 35 impossible

Contrôler la version en place avant de monter

Épingler la majeure suivante alors que l’instance n’y est pas encore prête fait échouer la migration au démarrage. Interroger d’abord le service lui-même : kanidmd domain upgrade-check pour Kanidm, nextcloud-occ status pour Nextcloud.

Le signal d’une montée à planifier est un warning à l’évaluation, émis dès que la version épinglée est dépréciée. La procédure détaillée de Kanidm, transposable aux autres, est décrite en fin de page SSO et identités.

Sauvegarder avant de monter

Ces migrations réécrivent le schéma de la base au premier démarrage de la nouvelle version, sans retour arrière. La sauvegarde préalable n’est pas une précaution de confort.

Kanidm stocke en SQLite, donc service arrêté :

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

Le * est essentiel : le journal d’écriture kanidm.db-wal survit à l’arrêt du service et porte les dernières transactions.

Nextcloud stocke en PostgreSQL, donc sans interruption : pg_dump -Fc prend un instantané transactionnel cohérent sur une base vive.

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

Ne pas omettre config.php : c’est lui qui porte le numéro de version installée, sans lequel une base restaurée ne repart pas.

Relire le dump avant de déployer

Un dump illisible ne se découvre jamais au bon moment. pg_restore -l liste son contenu sans rien restaurer :

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