5.1 KiB
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).
runtimedefaults to"docker". Each backend file gates oncfg.runtime == "<name>", so exactly one applies.- Docker enables autoprune, sets
insecure-registriesfromlocalDockerRegistries(defaultminipc1.lab.internal:5001), exposes metrics onmetricsPort(9323), adds the user to thedockergroup, and installsdocker-compose. - Podman enables
dockerCompat+ docker socket sodocker/oci-containerskeep working, allows plain-HTTP pulls fromlocalDockerRegistriesviavirtualisation.containers.registries.insecure, and installspodman-compose+podman-tui. openMetricsPortopens 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:
# macvlan (host can't reach its own containers)
skyg.nixos.common.containers.networks.macvlanLab = {
enable = true;
parent = "eno1";
ipRange = "10.0.101.16/28";
};
# ipvlan L2 mode (host can reach its own containers — preferred)
skyg.nixos.common.containers.networks.ipvlanLab = {
enable = true;
parent = "eno1";
ipRange = "10.0.101.16/28";
};
Each exposes a computed compose attribute for use in a group's networks option:
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:
skyg.nixos.common.containers.networks.extra.myNet = {
driver = "bridge";
subnet = "172.20.0.0/16";
};
Predefined fields: enable, parent, subnet (default 10.0.0.0/16), gateway (default
10.0.0.1), ipRange, internal. 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:
- Converts a Nix attrset into a real
compose.ymlviapkgs.formats.yaml. - Stages it to
/var/lib/container-services/<group>/compose.ymlat activation. - Manages the whole stack with one systemd oneshot unit per group:
container-services-<group>.service.
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 for the full option reference and day-2 ops.
For module implementation details, see container-services/ABOUTME.md.
Conventions
- Always select the runtime via
skyg.nixos.common.containers.runtime; do not enable both backends manually. virtualisation.oci-containers.backendis set by whichever runtime is active, so server service modules can declare containers backend-agnostically viavirtualisation.oci-containers.- Prefer
container-servicesfor new stacks. Only reach for rawvirtualisation.oci-containers.containersfor single-container services with no inter-container networking needs.