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).
runtimedefaults to"docker". Each backend file gates oncfg.runtime == "<name>", so exactly one applies.- Docker enables autoprune, sets
insecure-registriesfromlocalDockerRegistries(defaultminipc1.lab.internal:5001), adds the user to thedockergroup, and installsdocker-compose. Engine metrics are deliberately off (removed; no scraper, unauthenticated). - Podman enables
dockerCompat+ docker socket sodocker/oci-containerskeep working, allows plain-HTTP pulls fromlocalDockerRegistriesviavirtualisation.containers.registries.insecure, and installspodman-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:
# 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:
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, 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:
- 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.