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.
3.4 KiB
3.4 KiB
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
- User declares a group under
skyg.nixos.common.container-services.<group> options.nixvalidates the structurelib.nixprovides runtime dispatch (docker vs podman)compose.nixrenders a YAML compose file with all servicesfiles.nixcollects custom files, generates write commands, and builds file volume mountssystemd.nixbuilds oneshot units to manage the stackdefault.nixwires 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:
- Add it to the submodule in
options.nix - Update the builder(s) in
compose.nix,files.nix, orsystemd.nixas needed - Update
user-guide.mdwith 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 inskyg.nixos.common.containers.networksexists before a stack starts - Each unit puts the runtime CLI (
pkgs.podman/pkgs.docker) andcoreutilsonPATH:podman-composeshells out to a barepodman, and NixOS systemd services do not inherit/run/current-system/sw/bin(Docker worked without this only becausedocker-composev2 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
restartTriggersto the files-write script, so editing anyfilesentry 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 withsystemctl 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