Service modules

Note

A service module provides a ready-to-use service (daemon).

✨ darkone.service.adguardhome

Full-configured AdGuard Home for local gateway / router.

Note

This configuration reads the network conf in config.yaml file. It uses the DNF dnsmasq module as upstream DNS and DHCP.

• enable bool Enable local adguardhome service

darkone.service.adguardhome.enable = false;

---

✨ darkone.service.ai

Local Artifical Intelligence (open-webui + ollama + llms).

• enable bool Enable local AI service

darkone.service.ai.enable = false;

---

✨ darkone.service.audio

Audio services: alsa, pulse (not jack for the moment). Automatically adds users to the audio group when enabled.

• enable bool Enable sound system

darkone.service.audio.enable = false;

---

✨ darkone.service.dnsmasq

Pre-configured dnsmasq for local gateway / router.

Note

This configuration reads the network conf in config.yaml file. It is the essential functionality of the local gateway.

• enable bool Enable local dnsmasq service

darkone.service.dnsmasq.enable = false;

---

✨ darkone.service.docs

A full-configured LaSuite Docs module.

• enable bool Enable local docs service
• s3Host str S3 backend hostname
• s3Port port S3 backend port
• s3Bucket str S3 bucket name for document storage

darkone.service.docs = {
  enable = false;
  s3Host = "127.0.0.1";
  s3Port = dnfConfig.network.ports.garage;
  s3Bucket = "docs";
};

---

✨ darkone.service.element

Element web client for local matrix service.

• enable bool Enable local element service

darkone.service.element.enable = false;

---

✨ darkone.service.fail2ban

Fail2ban DNF specific module.

• enable bool Enable fail2ban with DNF specificities

darkone.service.fail2ban.enable = false;

---

✨ darkone.service.forgejo

A full-configured forgejo git forge.

• enable bool Enable local forgejo service

darkone.service.forgejo.enable = false;

---

✨ darkone.service.garage

A full-configured local Garage S3 service.

Provides an internal S3-compatible object storage backend accessible only on 127.0.0.1:3900.

Manual buckets creation

Buckets are NOT created automatically by this module. Each consumer service provisions its own bucket and access key via a dedicated systemd oneshot unit ordered After= garage-init.service. Per-consumer credentials are stored in sops as garage-<consumer>-key-id and garage-<consumer>-key-secret, imported into Garage on first boot.

Multi-node cluster migration

Single-node, replication_factor = 1. To grow into a multi-node cluster, bump replication_factor, expose rpc_public_addr on the mesh, and extend garage-init to drive a multi-node layout.

Cluster layout initialization

If it fails, wait until the garage service is fully operational, then restart it.

• enable bool Enable local Garage S3 service
• srvPort port S3 API port exposed on the internal IP
• s3Region str S3 region name (must match consumer config)
• capacity str Node storage capacity hint passed to garage layout assign. Used only at first boot for layout initialization; does not act as a hard quota on the underlying filesystem. Supported suffixes: B, KB, MB, GB, TB, PB.

darkone.service.garage = {
  enable = false;
  srvPort = srvPort;
  s3Region = s3Region;
  capacity = "500GB";
};

---

✨ darkone.service.geneweb

GeneWeb — Powerful Genealogy Service.

Service currently being validated

DNF wrapper around the nixpkgs module (from PR #522751 🡕).

Database declaration

To declare a base.gw file (default dir is /var/lib/geneweb), add this in your server configuration:

services.geneweb.databases.base = {};

SOPS secrets

The option enablePasswords reads friend and wizard passwords from the sops secrets geneweb-friend and geneweb-wizard. If enabled, add the entries to usr/secrets/ before rebuilding, otherwise sops-nix activation will fail.

Important note: Sops passwords must be sent in plain text to the Geneweb daemon. For greater security, it is better to define these passwords in the database configuration file (your-base.gwf) rather than using enablePasswords.

• enable bool Enable local GeneWeb genealogy service
• enablePasswords bool Enable sops passwords (not recommanded)

darkone.service.geneweb = {
  enable = false;
  enablePasswords = false;
};

---

✨ darkone.service.harmonia

Harmonia: local Nix binary cache server (serves this host’s /nix/store).

Exposes locally built / realised store paths over plain HTTP (port 5000), signed with the deployment-wide binary-cache key. Enable per host from usr/config.yaml (services.harmonia), like any other DNF service.

How Harmonia Services Work with NCPS

Harmonia is a source of packages; ncps is the per-zone caching proxy that clients actually talk to. Each zone’s ncps server automatically adds, as upstreams:

• the harmonia instances of its own zone (highest priority), then
• any harmonia flagged global (typically on the HCS),

and never the harmonia of other (non-global) zones. Clients fetch only through ncps; harmonia’s signature is passed through unchanged, so every host trusts the deployment-wide harmonia public key (usr/secrets/harmonia.pub). Transport is plain HTTP on the trusted LAN / VPN: integrity comes from the NAR signature, not from TLS.

Signing key provisioning

just configure-admin-host auto-generates the deployment-wide key pair when usr/secrets/harmonia.pub is missing: the public key is committed and the private key is injected into the sops secret harmonia-secret-key.

• enable bool Enable a local Harmonia Nix binary cache server

darkone.service.harmonia.enable = false;

---

✨ darkone.service.headscale

A full-configured headscale service for HCS.

• enable bool Enable headscale DNF service
• enableGRPC bool Open GRPC TCP port

darkone.service.headscale = {
  enable = false;
  enableGRPC = false;
};

---

✨ darkone.service.home-assistant

A Home Assistant with some plugins (wip).

• enable bool Enable home assitant

darkone.service.home-assistant.enable = false;

---

✨ darkone.service.homepage

Dynamically configured homepage dashboard for your local network.

Note

For each DNF service enabled, an entry is automatically added to the homepage configuration.

• enable bool Enable homepage dashboard + httpd + host
• localServices listOf attrs Services to add in Local Applications section
• globalServices listOf attrs Full network common & public-accessible services
• remoteServices listOf attrs Services to add in Remote Applications section
• bookmarks listOf attrs Replace default bookmarks (links)
• widgets listOf attrs Replace default widgets

darkone.service.homepage = {
  enable = false;
  localServices = [ ];
  globalServices = [ ];
  remoteServices = [ ];
  bookmarks = [ ];
  widgets = [ ];
};

---

✨ darkone.service.idm

Kanidm (identity manager) DNF Service.

• enable bool Enable local SSO with Kanidm
• oauth2 attrs OAuth2/OIDC client templates contributed by service modules. Kanidm provisions one client per matching entry in network.services, with clientId = dnfLib.oauth2ClientName.
  • enable bool Whether to provision OAuth2 clients for this template.
  • clientName nullOr str Override the kanidm client name. Defaults to dnfLib.oauth2ClientName.
  • displayName str Human-readable name shown on the kanidm consent screen.
  • imageFile path Application icon. Re-uploaded on every kanidm-provision run.
  • redirectPaths listOf str OAuth2 redirect paths (one per accepted callback URL).
  • landingPath str Auto-connect entry point path on the service.
  • enableLegacyCrypto bool Allow legacy JWT signing algorithms (eg. RS256).
  • allowInsecureClientDisablePkce bool Disable PKCE on the client (only for clients that do not implement it).
  • preferShortUsername nullOr bool Use the short username (no domain) in the preferred_username claim.
  • extra attrs Extra attributes merged into the provisioned client (claimMaps, etc).

darkone.service.idm = {
  enable = false;
  oauth2.enable = true;
  oauth2.clientName = null;
  oauth2.displayName = null;
  oauth2.imageFile = null;
  oauth2.redirectPaths = [ ];
  oauth2.landingPath = "/";
  oauth2.enableLegacyCrypto = false;
  oauth2.allowInsecureClientDisablePkce = false;
  oauth2.preferShortUsername = null;
  oauth2.extra = { };
};

---

✨ darkone.service.immich

Immich (photo management) full-configured service.

• enable bool Enable local immich service
• enableMachineLearning bool Enable machine learning features (face recognition, object detection)
• enableRedis bool Enable Redis for caching (recommended for performance)

darkone.service.immich = {
  enable = false;
  enableMachineLearning = false;
  enableRedis = false;
};

---

✨ darkone.service.jellyfin

A full-configured jellyfin server.

• enable bool Enable jellyfin service

darkone.service.jellyfin.enable = false;

---

✨ darkone.service.jitsi-meet

A full-configured jitsi-meet service.

• enable bool Enable local jitsi-meet service

darkone.service.jitsi-meet.enable = false;

---

✨ darkone.service.loki

Loki + Alloy, http stats with grafana.

Note

Centralized collection of Caddy access logs, consumed by Grafana via a provisioned Loki datasource and a dedicated dashboard.

Dual pattern aligned with monitoring.nix:

• enable : deploys the Loki server + Grafana datasource on the same host that runs the monitoring service (Grafana).
• isClient : deploys Alloy on each host running Caddy. Caddy logs are expected in JSON at /var/log/caddy/access-*.log (see dnf/modules/system/services.nix).

By default, enable follows darkone.service.monitoring.enable and isClient follows services.caddy.enable: setup is fully automatic once monitoring and Caddy are active.

Debugging & manual cleanup

Most common symptoms after a Loki (de)activation or Caddy log format change:

1. “NO DATA” on the Caddy dashboard despite incoming requests. Check the ingestion chain end-to-end:

# On the Caddy host: is Alloy running? reading files?
sudo systemctl status alloy --no-pager
sudo journalctl -u alloy -n 100 --no-pager | grep -iE 'error|permission'
ls -la /var/log/caddy/access-*.log   # must be caddy:caddy

# On the monitoring host: is Loki receiving anything?
# (replace <IP> with the monitoring host's internal IP, Loki does NOT
# bind on 127.0.0.1 — see http_listen_address = bindAddr)
curl -s http://<IP>:3100/loki/api/v1/labels | jq
curl -sG http://<IP>:3100/loki/api/v1/query \
     --data-urlencode 'query={job="caddy"}' | jq '.data.result | length'

2. alloy.service: mkdir data-alloy/remotecfg: permission denied. Orphaned ownership of /var/lib/alloy inherited from a former DynamicUser. The service ExecStartPre normally fixes it, but if stuck (e.g. unit in start-limit-hit):

sudo systemctl stop alloy
sudo chown -R caddy:caddy /var/lib/alloy
sudo systemctl reset-failed alloy
sudo systemctl start alloy

3. Grafana refuses to start: Datasource provisioning error: data source not found. UID conflict in SQLite DB after provision change (typically switching from auto-generated UID to uid = "loki"). The deleteDatasources option handles this in theory; otherwise manual purge:

sudo systemctl stop grafana
sudo sqlite3 /var/lib/grafana/grafana.db \
     "DELETE FROM data_source WHERE name='Loki';"
sudo systemctl reset-failed grafana
sudo systemctl start grafana

4. Stale Caddy log files (old naming with : or schema, e.g. access-http:__nextcloud.log). Harmless but pollute Alloy tail output. Clean up after a migration:

sudo rm /var/log/caddy/access-{http,https}:__*.log
sudo rm /var/log/caddy/access-:*.log     # variants `:80`, `:443`
sudo systemctl reload caddy              # optional

• enable bool Deploys the Loki server + Grafana datasource (colocated with Grafana).
• isClient bool Deploys Alloy to collect local Caddy access logs.
• retentionTime str Log retention duration in Loki (30 days by default).

darkone.service.loki = {
  enable = config.darkone.service.monitoring.enable;
  isClient = config.services.caddy.enable;
  retentionTime = "720h";
};

---

✨ darkone.service.matrix

DNF matrix (synapse) server.

• enable bool Enable matrix (synapse) service

darkone.service.matrix.enable = false;

---

✨ darkone.service.mealie

Mealie Recipe Management

• enable bool Enable mealie service

darkone.service.mealie.enable = false;

---

✨ darkone.service.minio

A full-configured local MinIO S3 service. (wip)

Provides an internal S3-compatible object storage backend accessible only on 127.0.0.1:9000. The console web UI runs on 127.0.0.1:9001 for administration and debugging.

Note

Buckets are NOT created automatically by this module. Each consumer service is responsible for creating its own buckets via a systemd postStart hook using the mc (MinIO Client) tool. Credentials are managed through sops.

• enable bool Enable local MinIO S3 service

darkone.service.minio.enable = false;

---

✨ darkone.service.monitoring

Supervision module with prometheus, grafana and node exporter.

Tip

This module is preconfigured with a configuration that allows you to monitor the operating system, network activity, resources, and performance. For each zone:

• All nodes with tag “monitoring-node” contains prometheus + node exporter.
• The node with service “monitoring” contains grafana.
• Only one monitoring host per zone is accepted.
• A tag “monitoring-node:[zone]” is attached to a monitoring host of the designed zone.

• enable bool Enable monitoring with prometheus, grafana and node exporter
• isNode bool Is a monitoring node
• retentionTime str Prometheus metrics retention duration
• kioskTarget str Target (relative, no /) for the automatic redirect to Grafana from the monitoring domain root. Overridden by the Loki module when active to point to a multi-source home dashboard.

darkone.service.monitoring = {
  enable = false;
  isNode = lib.hasAttrByPath [ "features" "monitoring-node" ] host;
  retentionTime = "30d";
  kioskTarget = "d/dnf-monitoring-home/home?kiosk";
};

---

✨ darkone.service.ncps

Nix cache proxy with NCPS module.

This module is activated by core. Server and clients are automatically detected.

Tip

To check if a host contains the local gateway in substituters:

nix --extra-experimental-features nix-command show-config | grep substituters
telnet <your-gateway> 8501

• enable bool Enable nix cache proxy for packages
• dataPath str Nix cache proxy cache folder
• extraOptions attrs services.ncps extra options

darkone.service.ncps = {
  enable = false;
  dataPath = "/var/cache/ncps";
  extraOptions = { };
};

---

✨ darkone.service.nextcloud

Nextcloud full-configured service.

Required sops secret

When enabled, this module reads the Nextcloud admin password from the sops secret nextcloud-admin-password. Add the entry to usr/secrets/ before rebuilding, otherwise sops-nix activation will fail.

• enable bool Enable local nextcloud service
• adminUser str Admin username for Nextcloud

darkone.service.nextcloud = {
  enable = false;
  adminUser = "admin";
};

---

✨ darkone.service.nfs

NFS server + client for home shares.

Note

This module is enabled if a nfs server is declared in the local network. It creates:

• A share (srv-dirs.homes) on the server.
• Mount dirs (/mnt/nfs/homes/[user]) on clients.

The nfs home manager script links xdg directories to mount dirs. In config.yaml file (hosts):

• Only one host have a service service.nfs.
• Clients need features = [ "nfs-client" ].

• enable bool Enable NFS DNF server (avoid enable manually)
• serverDomain str NFS Server FQDN

darkone.service.nfs = {
  enable = hasServer && (isServer || isClient);
  serverDomain = "nfs";
};

---

✨ darkone.service.outline

A full-configured outline wiki.

• enable bool Enable local outline service

darkone.service.outline.enable = false;

---

✨ darkone.service.oxicloud

OxiCloud — Fast Sovereign Cloud (file storage, WebDAV, CalDAV & CardDAV).

Service currently being validated

DNF wrapper around the nixpkgs module (from PR #516113 🡕). The oxicloud package already ships in nixpkgs; only the module is sourced from the fork (cf. flake.nix input nixpkgs-oxicloud).

SSO

When an idm (Kanidm) service exists on the network (zone or global), OIDC is wired automatically: an OAuth2 client is registered and OxiCloud is pointed at the Kanidm endpoints. Without idm, the upstream behaviour is left untouched (local password login only).

Storage

File storage, WebDAV, CalDAV and CardDAV are served on the same HTTP port, behind the Caddy reverse proxy. The PostgreSQL database is created locally.

• enable bool Enable local OxiCloud service

darkone.service.oxicloud.enable = false;

---

✨ darkone.service.postfix

Postfix SMTP Relay.

• enable bool Enable Postfix SMTP Relay

darkone.service.postfix.enable = false;

---

✨ darkone.service.printing

Printers and scanners.

• enable bool Default useful packages
• loadAll bool Full printers and scanners
• enableScanners bool Enable scanners
• enableHpPrinters bool HP printers only
• enableManualInstall bool Manual drivers installation

darkone.service.printing = {
  enable = false;
  loadAll = false;
  enableScanners = false;
  enableHpPrinters = false;
  enableManualInstall = false;
};

---

✨ darkone.service.restic

Restic backup module: REST server + per-host backup targets.

Two roles, one module

• Server: a host with restic in its config.yaml services runs the REST server (enableServer) and stores every host’s repository.
• Client: any host with enable = true declares backup targets (local path or rest:http://restic.<zone>:<port>).

Two passwords, do not confuse

• Repository passphrase: restic-password-<zone>, encrypts the repo content.
• REST credential: per-host restic/<hostname>/rest-password, authenticates the host against the REST server. Generated by just passwd-restic.

Example (machine config):

darkone.service.restic = {
  enable = true;
  targets = [
    { name = "main"; root = "rest:http://restic.ag.poncon.fr:8888";
      zone = "ag"; categories = [ "system" "nfs" ]; }
  ];
};

Repository layout per target:

<root>/<hostname>/system     <- "system" category (/ minus excludes)
<root>/<hostname>/srv/nfs    <- "nfs" category    (/srv/nfs/<...>)
<root>/<hostname>/srv/medias <- "medias" category (/srv/medias/<...>)

• enable bool Enable restic backup client
• enableDryRun bool Dry Run mode
• enableWaitRemoteFs bool Run backups only after remote-fs.target
• enableServer bool Enable restic REST server
• enableServerPrivateRepos bool Enforce per-host repository isolation (restic —private-repos). Only flip this on once every client deploys with its per-host REST credential.
• serverDataDir str Local storage root of the REST server (all hosts’ repos)
• targets listOf ( submodule { options = { name = lib.mkOption { type = str; default = "main"; description = "Target id, used in backup/unit names (<category>-<name>)"; }; root = lib.mkOption { type = str; default = "/mnt/backup/restic"; example = "rest:http://restic.${zone.domain}:${toString srvPort}"; description = "Repository root: local path or REST URL"; }; zone = lib.mkOption { type = str; default = zone.name; description = "Zone selecting the repo passphrase (restic-password-<zone>)"; }; categories = lib.mkOption { type = listOf ( enum [ "system" "nfs" "medias" ] ); default = [ "system" ]; description = "What to back up to this target"; }; }; } ) Backup destinations for this host (local path or REST URL)
  • name str Target id, used in backup/unit names (<category>-<name>)
  • root str Repository root: local path or REST URL
  • zone str Zone selecting the repo passphrase (restic-password-<zone>)
  • categories listOf ( enum [ "system" "nfs" "medias" ] ) What to back up to this target
• nfsPaths listOf str NFS dirs (/srv/nfs/<xxx>) included in the ‘nfs’ category
• mediasPaths listOf str Medias dirs (/srv/medias/<xxx>) included in the ‘medias’ category

darkone.service.restic = {
  enable = false;
  enableDryRun = false;
  enableWaitRemoteFs = false;
  enableServer = false;
  enableServerPrivateRepos = false;
  serverDataDir = "/mnt/backup/restic";
  targets = [ ];
  targets.name = "main";
  targets.root = "rest:http://restic.${zone.domain}:${toString srvPort}";
  targets.zone = zone.name;
  targets.categories = [ ];
  nfsPaths = [ ];
  mediasPaths = [ ];
};

---

✨ darkone.service.searx

A full-configured hardened search engine.

• enable bool Enable local search proxy

darkone.service.searx.enable = false;

---

✨ darkone.service.tailscale

Tailscale client service for HCS.

Note

A tailscale client to connect an external host to HCS. Do not use it to connect a gateway for a tailnet subnet.

• enable bool Enable tailscale client to connect HCS
• isGateway bool This tailscale node is a subnet gateway
• isExitNode bool Configure this client as exit node

darkone.service.tailscale = {
  enable = false;
  isGateway = false;
  isExitNode = false;
};

---

✨ darkone.service.turn

Coturn server (matrix).

Add DNS entries to optimize :

Type,Name,Priority,Pds,Port,Target
SRV,_stun._udp,0,0,3478,turn.mydomain.tld
SRV,_stun._tcp,0,0,3478,turn.mydomain.tld
SRV,_turn._udp,0,0,3478,turn.mydomain.tld
SRV,_turn._tcp,0,0,3478,turn.mydomain.tld
SRV,_turns._tcp,0,0,5349,turn.mydomain.tld

• enable bool Enable local turn service (visio)

darkone.service.turn.enable = false;

---

✨ darkone.service.vaultwarden

A full-configured vaultwarden server (wip).

• enable bool Enable local Vaultwarden service
• enableSmtp bool Enable SMTP to send emails (recommended)

darkone.service.vaultwarden = {
  enable = false;
  enableSmtp = true;
};

---