# Container Services — User Guide Declares Docker Compose stacks in Nix. Each group is rendered to a `compose.yml`, staged on disk, and managed by a systemd oneshot unit. ## Where things live | What | Path | | ---- | ---- | | Staged compose file | `/var/lib/container-services//compose.yml` | | Staged overrides file (composeFile groups with networks/volumes/extraConfig set) | `/var/lib/container-services//compose.overrides.yml` | | Nix store source | `/nix/store/…-compose.yml` (copied on each activation) | | Systemd unit | `container-services-.service` | | Container logs | `docker compose -p logs -f ` | | Unit journal | `journalctl -u container-services- -f` | ## Quick reference ```bash # See what's running docker compose -p ps # Follow container logs docker compose -p logs -f # Inspect the generated compose file cat /var/lib/container-services//compose.yml # Restart the stack (e.g. after nixos-rebuild switch) systemctl restart container-services- # Stop / start without a rebuild systemctl stop container-services- systemctl start container-services- # Shell into a running container docker compose -p exec bash # Pull a new image and recreate docker compose -p pull systemctl restart container-services- ``` ## Debugging ### Unit fails to start ```bash systemctl status container-services- journalctl -u container-services- -n 50 ``` Common causes: - **Docker not running** — `systemctl status docker` - **Secret path missing** — agenix may not have decrypted yet; check `systemctl status agenix` - **Port already in use** — another service holds the host port; `ss -tlnp | grep ` - **Image not pullable** — network issue or wrong image name; try `docker pull ` manually ### Container starts but misbehaves ```bash # Last 100 lines from the container docker compose -p logs --tail=100 # Inspect the compose file Nix generated cat /var/lib/container-services//compose.yml # Verify env file was read correctly (check what the container sees) docker compose -p exec env | grep ``` ### Permission errors on the data volume The container's init runs as root and chowns `/opt/data` to `PUID:PGID`. If it still fails, check ownership on the host: ```bash ls -la /var/lib/ # Should match PUID:PGID set in environment {} ``` If the directory was created by a previous run as root and never chowned, remove it and let Docker recreate it (named volumes are unaffected; only bind mounts need this): ```bash sudo rm -rf /var/lib/ systemctl restart container-services- ``` ### compose.yml looks wrong The file at `/var/lib/container-services//compose.yml` is overwritten on every `ExecStartPre`. If it looks wrong, check the Nix-rendered source in the store directly: ```bash # Find the store path systemctl cat container-services- | grep ExecStartPre # Then cat it cat /nix/store/…-compose.yml ``` If the store file is wrong, the bug is in your Nix options — rebuild with `nixos-rebuild build` and inspect the new store path before switching. ## Custom Files Mount custom files into containers via the `files` option: ```nix services.app = { image = "my/app"; files = { "/etc/app/config.yaml" = '' server: port: 8080 ''; "/usr/local/bin/startup.sh" = '' #!/bin/bash echo "Starting..." ''; }; }; ``` Files are: - Written to `/var/lib/container-services//files/` on the host - Mounted read-only into the container at the specified paths - Updated automatically when you rebuild - Changes trigger an automatic restart (via the `container-services--files` unit) --- ## Secret Compose Definitions (External `composeFile`) Keep a whole stack's definition out of version control by storing it in an agenix secret and pointing the group at it: ```nix # In your host file age.secrets.my-stack = { file = ../secrets/my-stack.age; }; skyg.nixos.common.container-services.my-stack = { enable = true; composeFile = config.age.secrets.my-stack.path; # Optional: merged in as a base layer, overridden by composeFile itself # on any overlapping keys. networks = { lan = { driver = "macvlan"; driver_opts.parent = "enp2s0"; }; }; }; ``` When `composeFile` is set, the module: - Copies that file to `/var/lib/container-services//compose.yml` at startup, just like a rendered one. It must define `services` itself — ignores this group's `services`/`files` blocks. - If this group also sets `networks`/`volumes`/`extraConfig`, those are rendered to `/var/lib/container-services//compose.overrides.yml` and passed to compose **before** the composeFile (`-f compose.overrides.yml -f compose.yml`), so compose's native multi-file merge applies — composeFile's own definitions win on any overlapping keys. - Requires exactly one of `composeFile` or `services` to be set (assertion). Notes: - `env_file:` entries in the external file resolve **relative to** `/var/lib/container-services//`. Use absolute paths (e.g. another agenix secret path) or inline `environment:` instead. - Create the secret with `skyg encrypt `. --- ## Limitations - **One unit per group.** No per-container systemd units. Use `docker compose logs` for container output, `journalctl` only for the start/stop lifecycle. - **`compose down` on stop.** Containers are removed when the unit stops. Data in bind mounts and named volumes is preserved. - **Compose project name == group name.** Keep group names DNS-label–safe (letters, digits, hyphens).