Podman Server

Introduction

The Podman server module layers repository conventions over quadlet-nix. Service modules declare containers, shared paths, dependencies, secret inputs, and derived environment files without creating bespoke systemd or Podman units.

Requirements

Container declarations require quadlet-nix. Stateful services also require declared storage datasets, while secret environment sources require agenix-managed files.

Use secretEnvironmentFiles for agenix-managed values and derivedEnvironmentFiles when a runtime file must combine secrets, generated values, or shell-expanded variables.

Invariants

  • Container dependencies refer to keys in podmanServer.containers.
  • Stateful container paths should come from storage.datasets or another declared persistent path.
  • Secret values must never be placed directly in Nix store-backed environment declarations.

Persistence

The module persists /var/lib/containers and /var/lib/podman-server when containers are active. Application data should remain in service-owned storage datasets rather than the container writable layer.

Troubleshooting

Inspect the generated <container>.service unit, apps-network.service, and podman-auto-update.service before debugging Podman directly. A missing /run/podman-server/<name>.env file points to podman-server-<name>-env.service or one of its agenix inputs. Container runtime state is persisted at /var/lib/containers and /var/lib/podman-server; empty application directories should instead be traced to the service-owned /storage/app/<service> dataset.

Options

podmanServer.containers

Containers rendered as Podman Quadlet units.

Type: attribute set of (submodule)

Default:

{ }

Example:

{
  example = {
    quadlet.containerConfig = {
      image = "docker.io/library/nginx:latest";
      publishPorts = [ "8080:80" ];
    };
    dependsOn = [ "database" ];
  };
}

Declared by:

podmanServer.containers.<name>.build

quadlet-nix build module for this container. When set, the container image uses the generated build ref.

Type: null or (submodule)

Default:

null

Declared by:

podmanServer.containers.<name>.dependsOn

Other Podman server container names this one requires and starts after.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.containers.<name>.derivedEnvironmentFiles

Keys from podmanServer.derivedEnvFiles appended to containerConfig.environmentFiles.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.containers.<name>.quadlet

quadlet-nix container module merged with Podman server defaults.

Type: submodule

Default:

{ }

Declared by:

podmanServer.containers.<name>.secretEnvironmentFiles

Secret environment files appended to containerConfig.environmentFiles.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.derivedEnvFiles

Runtime-rendered environment files declared by Podman server fragments.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

podmanServer.derivedEnvFiles.<name>.packages

Packages available while rendering.

Type: list of package

Default:

[ ]

Declared by:

podmanServer.derivedEnvFiles.<name>.after

Systemd units the renderer starts after.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.derivedEnvFiles.<name>.createIfMissing

Only render the environment file when it does not already exist.

Type: boolean

Default:

false

Declared by:

podmanServer.derivedEnvFiles.<name>.derivedEnvironmentFiles

Keys from podmanServer.derivedEnvFiles used while rendering.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.derivedEnvFiles.<name>.directoryMode

Permissions for the rendered environment file directory.

Type: string

Default:

"0755"

Declared by:

podmanServer.derivedEnvFiles.<name>.environmentFiles

Source environment files used while rendering.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.derivedEnvFiles.<name>.mode

Permissions for the rendered environment file.

Type: string

Default:

"0600"

Declared by:

podmanServer.derivedEnvFiles.<name>.path

Path to the rendered environment file.

Type: string

Default:

"/run/podman-server/‹name›.env"

Declared by:

podmanServer.derivedEnvFiles.<name>.secretEnvironmentFiles

Secret source environment files used while rendering.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.derivedEnvFiles.<name>.variables

Environment variables to write. Values may reference source variables with shell syntax.

Type: attribute set of string

Default:

{ }

Declared by:

podmanServer.derivedEnvFiles.<name>.wants

Systemd units wanted by the renderer.

Type: list of string

Default:

[ ]

Declared by:

podmanServer.networkInterface

Host bridge interface name for the shared Podman apps network.

Type: string

Default:

"podman-apps"

Declared by:

podmanServer.paths

Shared Podman server filesystem paths.

Type: attribute set of string

Default:

{ }

Declared by:

podmanServer.user.gid

Numeric ID of the Podman server host group.

Type: signed integer

Default:

1000

Declared by:

podmanServer.user.group

Name of the host group that owns Podman server state.

Type: string

Default:

"pbovbel"

Declared by:

podmanServer.user.name

Name of the host user that owns Podman server state.

Type: string

Default:

"pbovbel"

Declared by:

podmanServer.user.uid

Numeric ID of the Podman server host user.

Type: signed integer

Default:

1000

Declared by: