Files
nixos-setup/modules/nixos/common/containers/container-services/ABOUTME.md
T
Hermenix a8bc08de43 container-services: queue the env-reload restart instead of blocking on it
The env-reload unit is a oneshot whose ExecStart was a blocking
systemctl restart of the group unit. When the stack's cold start failed
transiently (container-services-buzz on minipc1, where buzz-relay-1 came
up unhealthy and compose exited 1), the group unit recovered on its own a
few seconds later through its own Restart=on-failure, but the reload unit
had already exited 1 with no restart policy and stayed failed until the
next env file write.

The trigger unit should queue the restart, not own the health of the whole
stack: pass --no-block. Real failures still surface on the group unit,
which carries Restart=on-failure and the start limit and is what the fleet
scan reports.
2026-11-09 15:04:30 +00:00

59 lines
3.4 KiB
Markdown

# container-services/
Custom compose-style container service groups for systemd.
## Files
| File | Purpose |
| ------------- | --------------------------------------------------------------------------------------------- |
| `default.nix` | Main module entry point; imports options and wires everything |
| `options.nix` | All `skyg.nixos.common.container-services.*` option declarations |
| `lib.nix` | Shared helpers (runtime dispatch, path sanitization, env file collection) |
| `compose.nix` | YAML composition (mkComposeService, mkComposeAttrs, mkComposeFile, mkOverridesFile) |
| `files.nix` | File mounting logic (getAllFiles, mkFileVolumesForService, mkFilesScriptFile, mkFilesService) |
| `systemd.nix` | Systemd unit builders (mkSystemdService, mkPathUnit, mkEnvReloadService) |
## How it works
1. User declares a group under `skyg.nixos.common.container-services.<group>`
2. `options.nix` validates the structure
3. `lib.nix` provides runtime dispatch (docker vs podman)
4. `compose.nix` renders a YAML compose file with all services
5. `files.nix` collects custom files, generates write commands, and builds file volume mounts
6. `systemd.nix` builds oneshot units to manage the stack
7. `default.nix` wires tmpfiles, services, and paths together
A group may instead set `composeFile` (e.g. to an agenix secret path) to use an
external, ready-made compose file for `services` instead of rendering from
options — useful for keeping sensitive definitions (NFS, env) out of version
control. `networks`/`volumes`/`extraConfig` set alongside `composeFile` still
apply: they're rendered as a base overrides file merged in via an earlier
compose `-f` flag, with `composeFile` itself taking precedence on overlaps.
See `user-guide.md` → "Secret Compose Definitions".
## Adding a new feature
If adding a new per-service option:
1. Add it to the submodule in `options.nix`
2. Update the builder(s) in `compose.nix`, `files.nix`, or `systemd.nix` as needed
3. Update `user-guide.md` with examples
## Architecture
- Each group gets **one** systemd unit (`container-services-<group>.service`) that manages the whole stack
- Group units are ordered after `container-networks.target`, so any network declared in
`skyg.nixos.common.containers.networks` exists before a stack starts
- Each unit puts the runtime CLI (`pkgs.podman`/`pkgs.docker`) and `coreutils` on `PATH`:
`podman-compose` shells out to a bare `podman`, and NixOS systemd services do not inherit
`/run/current-system/sw/bin` (Docker worked without this only because `docker-compose` v2
talks to the socket directly)
- Custom files are collected and written by a separate unit (`container-services-<group>-files.service`)
- The group's unit sets `restartTriggers` to the files-write script, so editing any
`files` entry restarts the stack on the next switch (services that read files at
startup, like Gitea templates, otherwise keep serving the old content)
- Env file changes trigger a path unit that restarts the stack (`container-services-<group>-env-reload.*`);
the restart is queued with `systemctl restart --no-block`, so the reload unit does not wait for or
inherit the health of the stack it restarted
- Compose files are rendered to the store and staged to `/var/lib/container-services/<group>/compose.yml`