Glossary
Nixda Stack uses ubiquitous language where terms have specific meanings within bounded contexts. The same word may carry different semantics depending on whether you’re writing configuration, debugging networking, or examining runtime behavior.
Bounded Contexts
| Context | Scope | Description |
|---|---|---|
| [Configuration] | NixOS module options | Terms used in nixda.zones.* declarations |
| [Network] | L2/L3 infrastructure | Terms describing VLAN, IP, and bridge topology |
| [Runtime] | systemd/container lifecycle | Terms for running workloads and their management |
| [DNS] | Service discovery | Terms for name resolution and routing |
| [Proxy] | Reverse proxy/TLS | Terms for HTTP routing and socket activation |
Architectural Concepts
Zone
| Context | Definition |
|---|---|
| [Configuration] | Network segment defined by VLAN ID, IP subnet, and port allocation baseline |
| [Network] | Isolated broadcast domain with dedicated bridge interface |
Source: zones/default.nix:17-41, stack/networking.nix:40-46
Zone Name
| Context | Definition |
|---|---|
| [Configuration] | String key identifying a zone (e.g., “management”, “private”, “business”) |
| [DNS] | Second-level domain component: *.${zoneName}.lan |
Source: service/interface.nix:11-15, stack/lib.nix:27-28
Deployment
| Context | Definition |
|---|---|
| [Configuration] | Service definition within a zone specifying identity, networking, and runtime |
A deployment describes the desired state of a service. It does not execute code; it declares what should run.
Source: service/interface.nix:1-140
Instance
| Context | Definition |
|---|---|
| [Runtime] | Running systemd unit(s) created from a deployment |
An instance is the actual workload — the container, VM, or process currently executing.
Source: native-service.nix:31, oci-service.nix:115
Service Registration
| Context | Definition |
|---|---|
| [Configuration] | Admission record created when operator declares a service in a zone’s catalog |
Records allocated IP and timestamp; created once per (zone, service) pair, never mutated.
Source: specs/catalog.allium:63-68
Blueprint
| Context | Definition |
|---|---|
| [Configuration] | Reusable service template declared via nixda.catalog |
Blueprints provide pre-configured service templates that can be instantiated into deployments.
Network Topology
VLAN
| Context | Definition |
|---|---|
| [Network] | IEEE 802.1Q tag (1-4094) for L2 segmentation |
| [Configuration] | Zone property mapping zone to network segment |
Source: zones/default.nix:19-22
Subnet Prefix
| Context | Definition |
|---|---|
| [Network] | First three octets of zone IP range (e.g., “10.100.10”) |
The fourth octet is reserved for host allocation based on service ID.
Source: zones/default.nix:30-33
Trunk Interface
| Context | Definition |
|---|---|
| [Network] | Physical NIC carrying tagged VLAN frames |
Example: eno3
Source: stack/networking.nix:27-30
Bridge
| Context | Definition |
|---|---|
| [Network] | Linux bridge br${VLAN_ID} connecting zone services |
Examples: br10, br20, br30
Source: stack/lib.nix:18-19
Host Bridge Address
| Context | Definition |
|---|---|
| [Network] | IP .254 on zone bridge; host’s entry point per zone |
This is the address services use to reach the host. Not the L3 gateway.
Source: stack/lib.nix:24-25
Podman Network
| Context | Definition |
|---|---|
| [Network] | Per-zone Netavark bridge network for OCI containers; DNS disabled |
| [Runtime] | Created once per zone with its first OCI service |
Name: zone-${zone.label}, subnet: ${zone.subnet}.0/24, gateway: ${zone.subnet}.254
Source: oci-service.nix:47-100
L3 Gateway
| Context | Definition |
|---|---|
| [Network] | IP .1 on upstream router; inter-zone routing |
This address lives on the upstream router, not on the Nixda host.
Source: stack/networking.nix:9
Gateway (Ambiguous)
The term “gateway” appears in configuration but may refer to either:
- Host Bridge Address (
.254) — for service-to-host communication - L3 Gateway (
.1) — for inter-zone routing
When precision matters, use the qualified terms above.
Service Identity
Name
| Context | Definition |
|---|---|
| [Configuration] | String key in zone’s services attrset |
| [DNS] | Hostname component: ${name}.${zone}.lan |
| [Runtime] | systemd unit suffix: container@${name}, podman-${name} |
Source: proxy-service.nix:51-61, stack/lib.nix:27-28
ID
| Context | Definition |
|---|---|
| [Configuration] | Integer (1-254) unique within zone for IP allocation |
| [Network] | Fourth octet of service IP: ${subnet}.${id} |
Source: interface.nix:21-24, stack/lib.nix:22
Service IP
| Context | Definition |
|---|---|
| [Network] | Static IP derived from zone subnet and service ID |
Formula: ${zone.subnet}.${service.id}
Example: Zone subnet 10.100.20 + Service ID 11 = 10.100.20.11
Source: stack/lib.nix:22
Domain
| Context | Definition |
|---|---|
| [DNS] | Internal FQDN: ${name}.${zone}.lan |
Example: gitea.private.lan
Source: stack/lib.nix:27-28
has_proxy (derived)
| Context | Definition |
|---|---|
| [Configuration] | Boolean derived value: true when service declares at least one port |
Determines whether a DNS record and virtual host are created for the service.
Source: specs/main.allium:49
is_on_demand (derived)
| Context | Definition |
|---|---|
| [Configuration] | Boolean derived value: true when idle_timeout != null |
Determines socket activation and auto-start behavior. See also: On-Demand Service.
Source: specs/main.allium:52
Runtime Types
| Runtime | Context | Definition | Systemd Unit |
|---|---|---|---|
| Native | [Runtime] | NixOS container via systemd-nspawn | container@${name}.service |
| OCI | [Runtime] | Podman container with OCI image | podman-${name}.service |
| VM | [Runtime] | MicroVM with isolated kernel (stub) | microvm@${name}.service |
| System | [Runtime] | Host-native service; no isolation | null (no backend unit) |
Runtime (Term)
| Context | Definition |
|---|---|
| [Configuration] | Namespace in service definition selecting execution model |
| [Runtime] | The active execution environment of an instance |
| [Network] | Static IP association depends on runtime network type (Podman bridge vs nspawn bridge vs host) |
| [Proxy] | Backend unit name depends on runtime type |
Source: interface.nix:54-138
Native Container
| Context | Definition |
|---|---|
| [Runtime] | NixOS container (systemd-nspawn) with virtual Ethernet on zone bridge |
| [Network] | Uses host Unbound at .254 for DNS; firewall ports opened inside container |
Source: native-service.nix:31-71
OCI Container
| Context | Definition |
|---|---|
| [Runtime] | Podman container with OCI image; static IP on zone bridge; no port publishing |
| [Network] | Connects via per-zone Podman network (zone-${zone.label}) |
Properties: image, environment, volumes, pull_policy = "newer"
Source: oci-service.nix:100-140
System Service
| Context | Definition |
|---|---|
| [Runtime] | Host-level systemd service with no container isolation |
| [Network] | Firewall ports opened on host firewall; proxy reaches service via 127.0.0.1 |
Cannot be auto-applied by the module; must be manually composed to avoid infinite recursion.
Source: system-service.nix
Proxy & Activation
Reverse Proxy
| Context | Definition |
|---|---|
| [Proxy] | Caddy instance terminating TLS and routing to backends |
Source: proxy-service.nix:43-74
Virtual Host
| Context | Definition |
|---|---|
| [Proxy] | Caddy HTTPS configuration block for a service’s .lan domain with internal TLS |
| [DNS] | Target domain that A records resolve to |
Formula: Domain = ${name}.${zone}.lan, Backend = 127.0.0.1:${activation_port}
Source: proxy-service.nix:45-74
Gateway Route
| Context | Definition |
|---|---|
| [Proxy] | HTTP subpath route on shared gateway domain (e.g., gateway.example.com/servicename) |
Only created when gateway_domain is configured. strip_prefix controls whether the path prefix is removed before forwarding.
Source: proxy-service.nix:64-71
TLS Mode (Internal)
| Context | Definition |
|---|---|
| [Proxy] | Caddy TLS configuration using internal CA for .lan domains; no external ACME |
All services use tls internal by default.
Source: proxy-service.nix:57
Backend Address
| Context | Definition |
|---|---|
| [Proxy] | Destination IP:port for reverse proxy forwarding: always 127.0.0.1:${activation_port} |
Different from Service IP — the proxy always routes to a localhost socket, never directly to the container.
Source: proxy-service.nix:58,68
Strip Prefix
| Context | Definition |
|---|---|
| [Configuration] | Boolean (default: true) controlling whether Caddy removes the service name prefix from the gateway route path before forwarding |
| [Proxy] | Determines use of handle_path (strip) vs handle (preserve) directive |
Source: interface.nix:42-46, proxy-service.nix:67
Socket Activation
| Context | Definition |
|---|---|
| [Runtime] | systemd socket triggering instance start on traffic |
Enables scale-to-zero: services start on first request.
Source: proxy-service.nix:77-84
Socket Unit
| Context | Definition |
|---|---|
| [Runtime] | systemd socket proxy-${name}.socket listening on 127.0.0.1:${activation_port} |
Triggers the proxy unit on incoming traffic. restartTriggers cause reload when activation_port, backend_ip, backend_port, or idle_timeout changes.
Source: proxy-service.nix:78-98
Proxy Unit
| Context | Definition |
|---|---|
| [Runtime] | systemd service proxy-${name}.service running systemd-socket-proxyd |
Bridges socket to backend via backend_ip:backend_port. BindsTo creates a hard dependency on the backend unit; PropagatesStopTo stops the backend on idle.
Source: proxy-service.nix:102-131
Activation Port
| Context | Definition |
|---|---|
| [Proxy] | Local port: ${zone.startPort} + ${service.id} |
Bound to 127.0.0.1.
Source: proxy-service.nix:47-48
Auto Start
| Context | Definition |
|---|---|
| [Runtime] | Boolean controlling whether container/service starts at boot |
Formula: false if idle_timeout != null (on-demand), else true.
Source: proxy-service.nix:134-140
Idle Timeout
| Context | Definition |
|---|---|
| [Configuration] | Seconds of inactivity before instance stop |
| [Runtime] | Timer controlling instance lifecycle |
| Value | Meaning |
|---|---|
null | Always-on; no socket activation timeout; service starts at boot |
43200 | 12-hour inactivity timeout (default when option is set) |
| Positive integer | Custom timeout in seconds |
Source: interface.nix:48-52, proxy-service.nix:96-109
On-Demand Service
| Context | Definition |
|---|---|
| [Configuration] | Service with idle_timeout != null |
| [Runtime] | Instance that starts via socket activation and stops after idle timeout |
| [Proxy] | Service whose container has autoStart = false |
Formula: is_on_demand = idle_timeout != null
Source: proxy-service.nix:134-140, interface.nix:48-52
Backend Unit
| Context | Definition |
|---|---|
| [Runtime] | systemd service running the actual workload |
Maps to runtime type as follows:
| Runtime | Backend Unit |
|---|---|
| Native | container@${name}.service |
| OCI | podman-${name}.service |
| VM | microvm@${name}.service |
| System | null (no unit; proxy runs without BindsTo dependency) |
Source: proxy-service.nix:32-36
DNS & Discovery
.lan Zone
| Context | Definition |
|---|---|
| [DNS] | Local DNS zone for internal services |
Served by Unbound on the host.
Source: stack/dns.nix:19, 59
DNS Record
| Context | Definition |
|---|---|
| [DNS] | Unbound A record mapping service domain to reverse proxy IP (not service IP) |
Only created when has_proxy = true (service has ports).
Formula: ${name}.${zone}.lan A ${reverse_proxy_ip}
Source: stack/dns.nix:23-30
Reverse Proxy IP
| Context | Definition |
|---|---|
| [DNS] | IP address for all service A records |
| [Proxy] | Caddy’s listening address |
All service domains resolve to this IP; Caddy routes based on hostname.
Source: stack/dns.nix:35-38, stack/proxy.nix:35-38
Cross-Reference: Ambiguous Terms
| Term | [Configuration] | [Network] | [Runtime] | [DNS] | [Proxy] |
|---|---|---|---|---|---|
| Zone | Zone definition | Broadcast domain | — | Domain component | — |
| Name | Attrset key | — | Unit suffix | Hostname | — |
| ID | Allocation key | IP octet | — | — | — |
| Runtime | Selection namespace | Network type determines IP | Execution env | — | Backend unit name |
| Gateway | (ambiguous) | L3 or Host | — | — | — |
| Idle Timeout | Config option | — | Lifecycle timer | — | — |
| Reverse Proxy IP | — | — | — | A record target | Listen address |
| On-Demand Service | idle_timeout != null | — | Socket-activated instance | — | autoStart = false |
| has_proxy | Ports declared | — | — | Record created | Virtual host created |
| Backend Unit | — | — | Runtime-specific unit | — | BindsTo target |
| Strip Prefix | Boolean option | — | — | — | handle_path vs handle |