134 lines
5.2 KiB
Markdown
134 lines
5.2 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, metrics).
|
|
|
|
- `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`), exposes metrics on `metricsPort` (9323), adds the
|
|
user to the `docker` group, and installs `docker-compose`.
|
|
- **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`.
|
|
- `openMetricsPort` opens the metrics port in the firewall (Docker only).
|
|
|
|
### 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.metricsPort
|
|
skyg.nixos.common.containers.openMetricsPort
|
|
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.
|