Server Module

The Server module provides a cluster-aware configuration for server hosts in the flake. It must be explicitly enabled using the server.enable option.

Purpose

The primary purpose of this module is to establish a shared environment for servers in the cluster, defining coordinator nodes for discrete roles (IO, monitoring, database, storage, identity) and providing helper functions for inter-server communication and attribute collection.

Entry Point

• Main file: modules/nixos/server/default.nix

Options

server.dashboard.displayData

Display data for the section in the dashboard.

server.dashboard.icon

Icon for the section in the dashboard.

server.dashboard.items

Additional configuration for items managed by the IO Hosts dashy instance. This will be merged with the automatically generated configuration that is nested in a section with the name of the machine.

server.dashboard.items.<name>.icon

Icon for the item.

server.dashboard.items.<name>.title

Title of the item.

server.dashboard.items.<name>.url

URL for the item.

server.dashboard.name

Name of the section in the dashboard.

server.database.dependentServices

List of systemd service names that depend on io databases. These services will be automatically bound to the io-databases.target and will stop/start when databases become unavailable/available.

server.database.host

The hostname or IP address to use when connecting to managed databases.

This is “localhost” when running on the host, and when connecting from other hosts.

server.database.postgres

This option has no description.

server.database.postgres.<name>.database

This option has no description.

server.database.postgres.<name>.host

This option has no description.

server.database.postgres.<name>.password

This option has no description.

server.database.postgres.<name>.password.group

This option has no description.

server.database.postgres.<name>.password.owner

This option has no description.

server.database.postgres.<name>.password.path

This option has no description.

server.database.postgres.<name>.port

This option has no description.

server.database.postgres.<name>.user

This option has no description.

server.database.redis

This option has no description.

server.database.redis.<name>.database_id

This option has no description.

server.database.redis.<name>.host

This option has no description.

server.database.redis.<name>.port

This option has no description.

server.database.redis.<name>.prefix

This option has no description.

server.distributedBuilds.builderUser

The user to use when connecting to remote build daemons.

server.distributedBuilds.builders

A list of hostnames of remote build daemons to connect to for distributed builds.

server.enable

Whether to enable enable the server module.

server.fail2ban.enable

Whether to enable fail2ban intrusion detection.

server.fail2ban.exporterPort

Port for the fail2ban Prometheus exporter.

server.ioPrimaryHost

Which host is the primary coordinator for IO in the cluster.

This host will run the primary instances of databases, Operate the reverse proxy for handling incoming traffic, and will run the MinIO distributed storage cluster’s master node.

server.monitoring.collector.alerting.enable

Whether to enable Alertmanager and alert rules.

server.monitoring.collector.alerting.homeAssistant.enable

Whether to enable Home Assistant webhook alerting.

server.monitoring.collector.alerting.nextcloudTalk.enable

Whether to enable Nextcloud Talk webhook alerting.

server.monitoring.collector.enable

Whether to enable monitoring collector services (Prometheus, Loki, Grafana).

server.monitoring.collector.grafana.kanidm.enable

Whether to enable Kanidm OAuth2 authentication for Grafana.

server.monitoring.collector.otlp.bearerTokenSecret

SOPS secret path used as the bearer token for OTLP/HTTP ingestion.

server.monitoring.collector.otlp.enable

Whether to enable OTLP/HTTP ingestion via Grafana Alloy.

server.monitoring.collector.otlp.port

Port for the OTLP/HTTP ingestion endpoint.

server.monitoring.collector.otlp.subdomain

Subdomain used for the OTLP/HTTP ingestion endpoint.

server.monitoring.collector.proxmox.enable

Whether to enable Proxmox VE metrics collection.

server.monitoring.enable

Whether to enable monitoring for this server.

server.monitoring.exporters.caddy.enable

Whether to enable Caddy metrics exporter.

server.monitoring.exporters.fail2ban.enable

Whether to enable fail2ban metrics exporter.

server.monitoring.exporters.node.enable

Whether to enable node_exporter for system-level metrics.

server.monitoring.exporters.postgres.enable

Whether to enable PostgreSQL exporter.

server.monitoring.exporters.process.enable

Whether to enable Process exporter for monitoring specific processes.

server.monitoring.exporters.redis.enable

Whether to enable Redis exporter.

server.monitoring.logs.enable

Whether to enable Alloy log shipping.

server.monitoring.logs.extraConfiguration

Additional configuration for the alloy log processor. This is useful for adding custom Loki stages, relabeling rules, or write targets.

Note that the default configuration for processing the system journal is always included and does not need to be specified here.

server.monitoring.retention.logs

Loki log retention period.

server.monitoring.retention.metrics

Prometheus TSDB retention period.

server.monitoring.scrapeConfigs

Declarative scrape configs for services running on this host. These are collected by the monitoring primary host and converted into Prometheus scrape configurations.

server.monitoring.scrapeConfigs.<name>.bearer_token_secret

SOPS secret path for bearer token authentication. When set, the secret will be created on the monitoring primary host.

server.monitoring.scrapeConfigs.<name>.host

Host to scrape metrics from.

server.monitoring.scrapeConfigs.<name>.job_name

Prometheus job name for this scrape target.

server.monitoring.scrapeConfigs.<name>.metrics_path

HTTP path to the metrics endpoint.

server.monitoring.scrapeConfigs.<name>.port

Port the metrics endpoint listens on.

server.monitoring.scrapeConfigs.<name>.scheme

URL scheme for scraping.

server.monitoringPrimaryHost

Which host is the primary collector for monitoring in the cluster.

This host will run Prometheus, Loki, Grafana, and Alertmanager for centralized observability of the entire server cluster.

server.network.openPortsForSubnet.tcp

List of TCP ports to open on the firewall for each subnet.

server.network.openPortsForSubnet.udp

List of UDP ports to open on the firewall for each subnet.

server.network.subnets

This option has no description.

server.network.subnets.*.dns

DNS server for the subnet.

server.network.subnets.*.domain

Domain name for the subnet.

server.network.subnets.*.ipv4

IPv4 configuration for the subnet.

server.network.subnets.*.ipv4.arpa

ARPA notation for reverse DNS lookups.

server.network.subnets.*.ipv4.cidr

CIDR notation for the IP range.

server.network.subnets.*.ipv6

IPv6 configuration for the subnet.

server.network.subnets.*.ipv6.arpa

ARPA notation for reverse DNS lookups.

server.network.subnets.*.ipv6.cidr

CIDR notation for the IP range.

server.proxy.domain

The base domain for all virtual hosts.

server.proxy.extensions

Registry of proxy extensions. Each extension provides config functions that are injected into vhost Caddy blocks, sorted by priority.

server.proxy.extensions.<name>.config

Function: vhostName -> vhostAttrSet -> hostConfig -> string. Returns Caddy directives to inject, or ‘’ for no-op. The vhostAttrSet includes the resolved extraConfig (already localhost-replaced) as _resolvedExtraConfig.

server.proxy.extensions.<name>.consumesExtraConfig

Whether this extension embeds extraConfig inside its output. When true, config.nix skips the post-extension extraConfig append for this vhost.

server.proxy.extensions.<name>.enable

Whether this extension is globally enabled. Each extension SHOULD auto-detect whether it has work to do and set this to true via mkDefault in its module config. User can explicitly override to force-disable (higher merge priority than mkDefault).

server.proxy.extensions.<name>.globalConfig

Function: hostConfig -> string. Returns Caddy directives to inject into the top-level globalConfig block. Only called on the IO primary host. Sorted by priority across extensions.

server.proxy.extensions.<name>.priority

Lower values = earlier in Caddy config. Priority ranges: 0-49 reserved, 50-99 auth, 100-199 general, 200+ post-processing.

server.proxy.extensions.<name>.vhostModule

Optional module to inject into each vhost submodule. Use options.<extensionName> (relative to vhost scope) to declare per-vhost options.

server.proxy.kanidmContexts

Shared Kanidm OAuth2 context configurations.

server.proxy.kanidmContexts.<name>.allowGroups

Default list of Kanidm groups allowed to access virtualHosts using this context.

server.proxy.kanidmContexts.<name>.authDomain

The domain where Kanidm is hosted. Defaults to auth.<server.proxy.domain> if not specified.

server.proxy.kanidmContexts.<name>.scopes

OAuth scopes to request from Kanidm.

server.proxy.kanidmContexts.<name>.tokenLifetime

Token lifetime in seconds for the authentication portal.

server.proxy.virtualHosts

Virtual hosts to be handled by the IO server and forwarded to the respective backend.

server.proxy.virtualHosts.<name>.aliases

A list of virtual host names that should be routed using this configuration. Options added here will inherit the base domain specified in <server.proxy.domain>.

server.proxy.virtualHosts.<name>.baseUrl

The base url including the configured base domain name.

server.proxy.virtualHosts.<name>.extensions

List of extension names to enable for this virtual host. When null (default), all globally enabled extensions apply. When set to a list, only those named extensions apply. Set to [] to disable all extensions for this vhost.

server.proxy.virtualHosts.<name>.extraConfig

Configuration to be placed in the caddy virtualHost extraConfig.

server.proxy.virtualHosts.<name>.kanidm

Enable Kanidm OAuth2 authentication for this virtual host.

server.proxy.virtualHosts.<name>.kanidm.allowGroups

Default list of Kanidm groups allowed to access virtualHosts using this context.

server.proxy.virtualHosts.<name>.kanidm.authDomain

The domain where Kanidm is hosted. Defaults to auth.<server.proxy.domain> if not specified.

server.proxy.virtualHosts.<name>.kanidm.bypassPaths

List of path patterns that should bypass authentication.

server.proxy.virtualHosts.<name>.kanidm.context

The OAuth context name for this virtual host.

server.proxy.virtualHosts.<name>.kanidm.scopes

OAuth scopes to request from Kanidm.

server.proxy.virtualHosts.<name>.kanidm.tokenLifetime

Token lifetime in seconds for the authentication portal.

server.proxy.virtualHosts.<name>.l4

This option has no description.

server.proxy.virtualHosts.<name>.l4.config

Configuration for the L4 plugin.

server.proxy.virtualHosts.<name>.l4.listenPort

Port to listen on for L4 traffic.

server.proxy.virtualHosts.<name>.l4.protocol

Protocol for L4 listener.

server.proxy.virtualHosts.<name>.listenPorts

Port(s) to listen on for incoming traffic for this virtual host. If multiple ports are specified, the virtual host will be accessible on all of them.

server.proxy.virtualHosts.<name>.ports

Ports to be opened from the host for IO Hosts to forward traffic to.

server.proxy.virtualHosts.<name>.public

When enabled this service will be accessible to the public via Cloudflared Tunnels.

server.proxy.virtualHosts.<name>.requireApiKey

This option has no description.

server.proxy.virtualHosts.<name>.requireApiKey.bypassPaths

List of path patterns that bypass API key authentication.

server.proxy.virtualHosts.<name>.requireApiKey.enable

Enable API key authentication for this virtual host.

server.proxy.virtualHosts.<name>.useAcmeCerts

Whether to generate and use ACME certificates for this virtual host. If false, you must provide your own TLS configuration in extraConfig via the caddy tls directive.

server.sshShell.enable

Whether to enable Auto-enter a session-only devShell for root on interactive SSH logins..

server.sshShell.shellFile

Path to a single-file that defines a session-only environment. This file is evaluated by nix-shell and should import to use the system registry.

server.storage.swfsMount

Declarative storage mounts backed by MinIO or SeaweedFS.

Each entry creates a systemd-managed FUSE mount service plus an optional health-check timer.

server.storage.swfsMount.<name>.backend

The storage backend to mount.

server.storage.swfsMount.<name>.gid

Group ID that should own the mounted path.

server.storage.swfsMount.<name>.healthCheck.enable

Whether to monitor this mount and attempt automated recovery.

server.storage.swfsMount.<name>.healthCheck.interval

Systemd timer interval between mount health probes.

server.storage.swfsMount.<name>.healthCheck.reloadServices

Additional systemd services to reload after recovering this mount

server.storage.swfsMount.<name>.healthCheck.restartServices

Additional systemd services to restart after recovering this mount.

server.storage.swfsMount.<name>.healthCheck.timeout

Timeout applied to the mount health probe.

server.storage.swfsMount.<name>.minio.bucketName

The MinIO bucket to mount with s3fs.

server.storage.swfsMount.<name>.minio.credentialsFile

Path to the MinIO credentials file in ACCESS_KEY_ID:SECRET_ACCESS_KEY format.

When left null, the module provisions and uses the S3FS_AUTH/<NAME_IN_UPPERCASE> sops secret.

server.storage.swfsMount.<name>.minio.endpoint

The S3-compatible MinIO endpoint used by s3fs.

server.storage.swfsMount.<name>.minio.extraOptions

Additional -o options passed to s3fs.

server.storage.swfsMount.<name>.mountLocation

Path where the backend should be mounted.

server.storage.swfsMount.<name>.requiredByServices

Systemd services that must wait for this mount before starting.

server.storage.swfsMount.<name>.seaweedfs.allowOthers

Whether to allow non-owning users to access the SeaweedFS mount.

server.storage.swfsMount.<name>.seaweedfs.dirAutoCreate

Whether weed mount should create the mount directory when needed.

server.storage.swfsMount.<name>.seaweedfs.extraArgs

Additional arguments passed directly to weed mount.

server.storage.swfsMount.<name>.seaweedfs.filer

SeaweedFS filer address in host:port form.

server.storage.swfsMount.<name>.seaweedfs.filerPath

Remote filer path to expose through the mount.

server.storage.swfsMount.<name>.seaweedfs.gidMap

Optional local-to-filer GID mapping string for weed mount.

server.storage.swfsMount.<name>.seaweedfs.metadataFlushSeconds

How often weed mount flushes metadata to the filer.

server.storage.swfsMount.<name>.seaweedfs.readOnly

Whether the SeaweedFS mount should be read-only.

server.storage.swfsMount.<name>.seaweedfs.uidMap

Optional local-to-filer UID mapping string for weed mount.

server.storage.swfsMount.<name>.seaweedfs.writeBufferSizeMB

Optional write buffer cap passed to weed mount in megabytes.

server.storage.swfsMount.<name>.uid

User ID that should own the mounted path.

server.storage.swfsMount.<name>.umask

Umask applied to files and directories inside the mount.

Architecture / Services / Scope

Special Options and Behaviors

The main configuration entry point is server.enable. Once enabled, it sets up the server-specific baseline:

• Journald Persistence: Configured with a 7-day retention period, 256MB total max disk usage, and 512MB keep-free threshold. Per-file size is set to 32MB (1/8 of max use) to allow proper log rotation with ~7 archived files. All limits are defined as let variables in the module for consistency between the daemon config and the activation vacuum script. The activation script runs journalctl --vacuum on every deploy to immediately enforce the limits on existing logs.
• Pre-Switch Checks: Runs dix on system activation to report changes between generations.
• server.ioPrimaryHost: Specifies the hostname of the IO Coordinator. This host operates the reverse proxy for handling incoming traffic and manages IO-level coordination. This option is typically set on the coordinator host and used by other servers in the cluster for synchronization.
• server.monitoringPrimaryHost: Specifies the hostname of the Monitoring Coordinator. This host runs Prometheus, Loki, Grafana, and Alertmanager for centralized observability across the cluster.
• server.databasePrimaryHost: Specifies the hostname of the Database Coordinator. This host runs primary database instances for centralized data persistence across the cluster.
• server.storagePrimaryHost: Specifies the hostname of the Storage Coordinator. This host runs primary file and block storage services for centralized data serving across the cluster.
• server.authPrimaryHost: Specifies the hostname of the Identity Coordinator. This host runs primary authentication and authorization services for centralized identity management across the cluster.

Example Usage

To use the server module, it must be explicitly enabled in the host configuration.

# hosts/server/nixmon/default.nix
{
  server = {
    enable = true;
    # Set to the hostname of the cluster's coordinator node
    ioPrimaryHost = "nixio";
  };
}

Operational Notes / Assumptions

Generic Primary-Host Helpers

Generic helpers parameterized by any primary-host option value. These are used by submodules to check role assignment and fetch remote configuration:

• isPrimaryHost primaryHost value: Returns true if value matches primaryHost. Accepts either a raw hostname string or an attrset with a host.name attribute.
• isThisPrimaryHost primaryHost: Shorthand for isPrimaryHost primaryHost config — checks if the current host is the primary for a given role.
• getPrimaryHostConfig primaryHost: Returns the NixOS configuration of the host designated as the primary for a given role. On the primary host itself this returns config locally; on other hosts it fetches the remote configuration via self.nixosConfigurations.
• getPrimaryHostAttr primaryHost attrPath: Retrieves a specific attribute (expressed as a dot-separated path) from the primary host’s configuration.
• getOthersWhereExcept primaryHost func: Returns a list of server hostnames (excluding the given primary host) where func returns true. Useful for discovering non-primary nodes that match certain criteria.

Backward-Compatible IO Helpers

The existing IO-specific helpers (isIOPrimaryHost, isThisIOPrimaryHost, primaryIOHostConfig, getIOPrimaryHostAttr, getOthersWhere) remain available and now delegate to the generic helpers. They behave identically but are hard-wired to server.ioPrimaryHost. New submodules should prefer the generic helpers for role-agnostic code.

Server Attribute Collection

• This module provides many helper functions (like getAllAttrsFunc, collectAllAttrs, etc.) that are used by submodules to gather configuration data from other servers in the cluster.
• These helpers allow for dynamic configuration based on the state of other cluster nodes, such as building a global dashboard or a reverse proxy configuration.
• The IO Coordinator is a critical component of the cluster, as many services (like Dashy or shared ingress) rely on it as the central point of coordination.

References

• IO Coordinator
• Monitoring Coordinator
• Database Coordinator
• Storage Coordinator
• Identity Coordinator