Declaring Docker and containers on NixOS

Declarative Docker configuration on NixOS. Docker and Podman use different approaches and different NixOS configuration interfaces; check them against the relevant version.

Basic Configuration#

Minimal Enablement

# configuration.nix
{
  virtualisation.docker.enable = true;

  # 将自己的用户加入 docker 组
  users.users.alice = {
    extraGroups = [ "docker" ];
  };
}

sudo nixos-rebuild switch
# 重新登录后生效
docker run hello-world

Complete Configuration

{
  virtualisation.docker = {
    enable = true;
    # 自动清理旧镜像（每天一次）
    autoPrune = {
      enable = true;
      dates = "03:00";         # 每天凌晨 3 点
      flags = [ "--all" "--filter" "until=168h" ]; # 按创建时间过滤的示例，非最后使用时间；先确定回滚策略
    };
    # 存储驱动
    # storageDriver = "overlay2"; # 经典引擎示例，先确认当前后端，切换会使旧产物不可见
    # daemon JSON 配置（mirror 不等于自动可信）
    daemon.settings = {
      # 镜像加速地址（根据需要替换）
      registry-mirrors = [ "https://mirror.gcr.io" ];
      # 日志大小限制
      log-driver = "json-file";
      log-opts = {
        max-size = "10m";
        max-file = "3";
      };
    };
  };
}

Declarative Containers: The oci-containers Module#

NixOS has a built-in module for declaring containers directly, similar to a simplified Compose:

{
  virtualisation.oci-containers = {
    backend = "docker";    # 或 "podman"
    containers = {
      nginx = {
        image = "nginx:alpine";
        autoStart = true;
        ports = [ "127.0.0.1:8080:80" ];
        volumes = [
          "nginx_data:/usr/share/nginx/html"
        ];
      };

      postgres = {
        image = "postgres:16-alpine";
        autoStart = true;
        ports = [ "127.0.0.1:5432:5432" ];
        volumes = [
          "pgdata:/var/lib/postgresql/data"
        ];
        # 文件由外部凭据流程提供；不把秘密内容放入 Nix store
        environmentFiles = [ "/run/secrets/postgres.env" ];
        environment = {
          POSTGRES_DB = "myapp";
        };
      };
    };
  };
}

Limitations: this module does not implement the full Compose model. Its own dependsOn generates systemd After/Requires dependencies, and health/runtime options can be supplied through the corresponding interfaces or extraOptions, but it does not automatically provide Compose profiles or service_healthy dependency semantics. For complex applications, using docker compose and keeping the Compose file in Git remains the recommended approach.

Home Manager#

# home.nix
{
  # 不需要额外配置 Docker，系统级 virtualisation.docker 已足够
  # 如果需要在用户级管理 Docker，用：
  # home.file.".docker/config.json" = { ... };
}

Docker is primarily managed through system-level configuration. Do not configure credentials by writing a config.json containing auth/token data into the store as public home.file text. Separately verify support in the relevant system or user modules for a user-level rootless daemon, socket, and context.

Choosing Docker vs. Podman on NixOS#

The engines can coexist, but CLI and socket compatibility options may conflict. When enabling actual Docker, do not also let Podman take over the docker command:

{
  # 同时启用
  virtualisation.docker.enable = true;
  virtualisation.podman.enable = true;
  virtualisation.podman.dockerCompat = false;  # 保留真实 docker 命令
  virtualisation.podman.dockerSocket.enable = false; # 不接管 Docker socket
}

Verifying Builds, Activation, and Runtime Behavior#

nixos-rebuild build only verifies build outputs. The example switch activates the system and may restart services, so follow the deployment procedure. Logging in again after joining the docker group only determines when the permission change takes effect; it does not reduce the group's security risk. The controlled file /run/secrets/postgres.env must exist with restricted read access and contain the required database credentials; this configuration does not generate it automatically. Rootless mode uses a separate daemon/socket; running the CLI as an ordinary user does not automatically make the setup rootless.