Files
nixos-setup/modules/nixos/common/containers/ABOUTME.md
T
2026-09-26 02:41:43 -04:00

5.2 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).

  • 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:

# 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:

  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.
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.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.