Files
nixos-setup/modules/nixos/common/containers/ABOUTME.md
T
2026-10-16 16:59:09 -04:00

132 lines
5.1 KiB
Markdown

# modules/nixos/common/containers/
Container runtime configuration and compose-style service groups.
## Files
```
containers/
├── default.nix # Shared runtime options (runtime, enableOnBoot, registries, metrics)
├── docker.nix # Applied when runtime == "docker"
├── podman.nix # Applied when runtime == "podman" (dockerCompat + socket + registries)
├── networks.nix # Host-created container networks (skyg.nixos.common.containers.networks)
├── container-services/ # Compose-style service groups (modular implementation)
│ ├── default.nix
│ ├── options.nix
│ ├── lib.nix
│ ├── compose.nix
│ ├── files.nix
│ ├── systemd.nix
│ └── ABOUTME.md
└── user-guide.md # Full usage docs for container-services
```
## Runtime selection (`skyg.nixos.common.containers`)
Picks **one** of Docker or Podman based on `runtime` and configures it
consistently (compose tooling, user group membership, OCI backend).
- `runtime` defaults to `"docker"`. Each backend file gates on `cfg.runtime == "<name>"`,
so exactly one applies.
- **Docker** enables autoprune, sets `insecure-registries` from `localDockerRegistries`
(default `minipc1.lab.internal:5001`), adds the user to the `docker` group, and installs
`docker-compose`. Engine metrics are deliberately off (removed; no scraper, unauthenticated).
- **Podman** enables `dockerCompat` + docker socket so `docker`/`oci-containers` keep working,
allows plain-HTTP pulls from `localDockerRegistries` via
`virtualisation.containers.registries.insecure`, and installs `podman-compose` + `podman-tui`.
### Option namespace
```
skyg.nixos.common.containers.enable → false to disable the container runtime entirely
skyg.nixos.common.containers.runtime → "docker" | "podman"
skyg.nixos.common.containers.enableOnBoot
skyg.nixos.common.containers.localDockerRegistries
skyg.nixos.common.containers.networks.macvlanLab.* → predefined macvlan lab network
skyg.nixos.common.containers.networks.ipvlanLab.* → predefined ipvlan lab network
skyg.nixos.common.containers.networks.extra.<name>.* → custom networks (networks.nix)
```
## Host-created networks (`skyg.nixos.common.containers.networks`)
Creates container networks once on the host (one systemd oneshot each, ordered before
`container-networks.target`), independent of any compose project. This is how a _single_
network — e.g. one ipvlan network — is shared by several `container-services` groups
instead of being re-declared (and re-created) per stack.
Two predefined lab networks are available:
```nix
# macvlan (host can't reach its own containers)
skyg.nixos.common.containers.networks.macvlanLab = {
enable = true;
parent = "eno1";
};
# ipvlan L2 mode (host can reach its own containers — preferred)
skyg.nixos.common.containers.networks.ipvlanLab = {
enable = true;
parent = "eno1";
};
```
Each exposes a computed `compose` attribute for use in a group's `networks` option:
```nix
skyg.nixos.common.container-services.my-stack = {
networks.lan = config.skyg.nixos.common.containers.networks.ipvlanLab.compose;
services.app.networks.lan = { ipv4_address = "10.0.101.3"; };
};
```
For ad-hoc networks not covered by the predefined ones, use `networks.extra`:
```nix
skyg.nixos.common.containers.networks.extra.myNet = {
driver = "bridge";
subnet = "172.20.0.0/16";
};
```
Predefined fields: `enable`, `parent`, `subnet`, `gateway`, `ipRange`, `internal`. `subnet`,
`gateway`, and `ipRange` default to `skyg.internalNetworkingMap.appNetwork` (see
`modules/main.nix`), so the lab network is declared once. Extra networks also have `name`,
`driver`, `driverOpts`.
Works with both docker and podman.
## Container service groups (`skyg.nixos.common.container-services`)
A compose-like abstraction that:
1. Converts a Nix attrset into a real `compose.yml` via `pkgs.formats.yaml`.
2. Stages it to `/var/lib/container-services/<group>/compose.yml` at activation.
3. Manages the whole stack with one systemd oneshot unit per group:
`container-services-<group>.service`.
```nix
skyg.nixos.common.container-services.my-stack = {
services.app = {
image = "example/app:latest";
ports = [ "8080:8080" ];
volumes = [ "/var/lib/app:/data" ];
environmentFiles = [ config.age.secrets.app-env.path ];
extraConfig.shm_size = "512m";
};
};
```
See [user-guide.md](./user-guide.md) for the full option reference and day-2 ops.
For module implementation details, see [container-services/ABOUTME.md](./container-services/ABOUTME.md).
## Conventions
- Always select the runtime via `skyg.nixos.common.containers.runtime`; do not enable both
backends manually.
- `virtualisation.oci-containers.backend` is set by whichever runtime is active, so server
service modules can declare containers backend-agnostically via `virtualisation.oci-containers`.
- Prefer `container-services` for new stacks. Only reach for raw
`virtualisation.oci-containers.containers` for single-container services with no
inter-container networking needs.