Container Options

This project extends Home Managers existing services.podman.containers options, to provide additional abstractions for example for Traefik or Homepage.

The options can be set directly on services.podman.container level, or through the stack aliases provided with this project. For example, the following two configurations are equivalent:

nps.stacks = {
    streaming.containers.jellyfin.expose = true;
};

services.podman.containers.jellyfin.expose = true;

The following lists all extension options that will be added by this project.



services.podman.containers.<name>.alloy.enable

Whether to enable Alloy Log Scraping. If enabled, Alloy will scrape logs from the container and ship them to Loki.; .

Type: boolean

Default: false

Example: true

Declared by:

services.podman.containers.<name>.dependsOn

List of systemd resources that this container depends on. This is a hard requirement and will setup systemd Require and After attributes. When specifying a dependency on another container, use the option dependsOnContainer instead.

See

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.dependsOnContainer

List of containers that this container depends on. Similar to dependsOn, but will automatically apply correct pre- and suffix for the generated systemd services.

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.environment

Environment variables to set in the container.

Type: attribute set of (null or boolean or signed integer or string or absolute path or list of (null or boolean or signed integer or string or absolute path))

Default: { }

Example:

{
  VAR1 = "0:100";
  VAR2 = true;
  VAR3 = 5;
}

Declared by:

services.podman.containers.<name>.expose

Whether the service should be exposed (e.g. reachable from external IP addresses). When set to false, the private middleware will be applied by Traefik. The private middleware will only allow requests from private CIDR ranges.

When set to true, the public middleware will be applied. The public middleware will allow access from the internet. It will be configured with a rate limit, security headers and a geoblock plugin (if enabled). If enabled, Crowdsec will also be added to the public middleware chain.

Type: boolean

Default: false

Declared by:

services.podman.containers.<name>.extraEnv

Convinience wrapper option for passing environment variables to the container. The values of the environment variables can either be a primitive value or a path to a file.

In case of passing a path (using the fromFile attribure), the file will be read and the content will be set as the value of the environment variable. Useful for containers that don’t support passing environment variables using the “_FILE” pattern.

Type: attribute set of (null or boolean or signed integer or string or absolute path or (submodule))

Default: { }

Example:

{
  API_KEY = {
    fromFile = "/home/user/api-key";
  };
  DB_PASSWORD = {
    fromFile = "/some/path/secrets/db-password";
  };
  DB_URL = {
    fromTemplate = "postgresql://user:{{ file.Read `/run/secrets/db_password` }}@localhost:5432/mydb";
  };
  ENCRYPTION_KEY = "literal-value";
}

Declared by:

services.podman.containers.<name>.fileEnvMount

Convenience wrapper option, that simplifies passing _FILE based environment variables. For each attribute in the attrset, a volume mapping from sourcePath to destPath will be added, and an environment variable will be set to the destPath.

Example:

API_KEY_FILE = {
  srcPath = "/host/api-key.txt";
  dstPath = "/container/api-key.txt";
};

will add a volume to the container, e.g.:

volumes = [${sourcePath}:${destPath}];

and also add an environment variable:

env.API_KEY_FILE = destPath;

You can also provide a simple path, which will be treated as the sourcePath:

DB_PASSWORD_FILE = ./secrets/db-password.txt;

The destPath will be inferred.

Type: attribute set of (absolute path or (submodule))

Default: { }

Example:

{
  API_KEY_FILE = {
    destPath = "/app/config/api-key.txt";
    sourcePath = "/secrets/api-key.txt";
  };
  DB_PASSWORD_FILE = "/run/secrets/db-password.txt";
}

Declared by:

services.podman.containers.<name>.forwardAuth.enable

Whether to enable forward auth. This will enable the authelia Traefik middleware for this container. Every request will be forwarded to be authorized by Authelia first.

Optionally, access control rules for this container can be specified in the settings. They will be added to the Authelia settings.

See https://www.authelia.com/configuration/security/access-control/

Type: boolean

Default: false

Declared by:

services.podman.containers.<name>.forwardAuth.middlewareOrder

Order of the authelia middleware. Multiple middlewares will be called in order by Traefik, with lower orders being called first.

Type: signed integer

Default: 1000

Declared by:

services.podman.containers.<name>.forwardAuth.rules

Rules matching a request. When all criteria of a rule match the request, the defined policy is applied.

See https://www.authelia.com/configuration/security/access-control/#rules

Type: list of (submodule)

Default: [ ]

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.domain

Domain(s) that will be matched for the rule. Defaults to the servie domain registered in Traefik. Either this, or the domain_regex options has to be set.

See https://www.authelia.com/configuration/security/access-control/#domain

Type: list of string

Default: [ containerCfg.traefik.serviceUrl ]

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.domain_regex

Regex(es) criteria matching the domain. Defaults to the servie domain registered in Traefik. Has to be set if the domain is unset.

See https://www.authelia.com/configuration/security/access-control/#domain_regex

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.methods

Critera matching the HTTP request method.

See https://www.authelia.com/configuration/security/access-control/#methods

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.networks

Critera matching the network. Can be a list of IP addresses, CIDR ranges or named network definitions.

See https://www.authelia.com/configuration/security/access-control/#networks

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.policy

The specific policy to apply to the selected rule. This is not criteria for a match, this is the action to take when a match is made.

See https://www.authelia.com/configuration/security/access-control/#policy

Type: one of “”, “deny”, “bypass”, “one_factor”, “two_factor”

Default: ""

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.resources

Critera matching the path and query parameter using regular expressions.

See https://www.authelia.com/configuration/security/access-control/#resources

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.forwardAuth.rules.*.subject

Criteria that matches the subject.

See https://www.authelia.com/configuration/security/access-control/#subject

Type: list of (string or list of string)

Default: [ ]

Declared by:

services.podman.containers.<name>.forwardAuth.rulesOrder

Order of rules when merged into the authelia settings. The order will be applied using lib.mkOrder <order> when applying the rules in the Authelia settings. Lower numbers mean the rules will appear earlier in the access_control.rules list, which give them a higher priority.

See https://www.authelia.com/configuration/security/access-control/#rule-matching-concept-1-sequential-order

Type: signed integer

Default: 1000

Declared by:

services.podman.containers.<name>.gatus.enable

Whether to enable gatus.

Type: boolean

Default: false

Example: true

Declared by:

services.podman.containers.<name>.gatus.settings

Endpoint Settings for the container. Will be added to the Gatus endpoint configuration.

See https://github.com/TwiN/gatus?tab=readme-ov-file#endpoints

Type: YAML 1.1 value

Default: { }

Declared by:

services.podman.containers.<name>.glance

Settings for the service.

See https://github.com/glanceapp/glance/blob/main/docs/configuration.md#docker-containers

Type: YAML 1.1 value

Default: { }

Declared by:

services.podman.containers.<name>.glance.category

The category under which the service will be listed on the dashboard.

Type: null or string

Default: null

Declared by:

services.podman.containers.<name>.glance.name

The name of the service as it will displayed on the dashboard.

Type: string

Default: lib.toSentenceCase <containerName>

Declared by:

services.podman.containers.<name>.glance.url

The URL of the service.

Type: string

Default: ""

Declared by:

services.podman.containers.<name>.homepage.category

The category under which the service will be listed on the Homepage dashboard.

Type: null or string

Default: null

Declared by:

services.podman.containers.<name>.homepage.name

The name of the service as it will appear on the Homepage dashboard. Defaults to the container name.

Type: string

Default: lib.toSentenceCase <containerName>

Declared by:

services.podman.containers.<name>.homepage.settings

Settings for the Homepage service. This can include icon, href, description, widget configuration, etc.

See https://gethomepage.dev/configs/services/#services/

Type: YAML 1.1 value

Default: { }

Declared by:

services.podman.containers.<name>.port

Main port that Traefik will forward traffic to. If Traefik is disabled, it will instead be added to the “ports” section

Type: null or string or signed integer

Default: null

Declared by:

services.podman.containers.<name>.socketActivation

List of socket activation configurations for this container. Each entry should specify a port and optionally a file descriptor name. This will create a systemd socket that activates the container when accessed.

Will be used by containers like Traefik by default. Allows the container to access real-ip without the request being proxied through pasta/slirp4netns.

For details regarding rootless Podman networking and socket activation, see: https://github.com/eriksjolund/podman-networking-docs

Type: list of (submodule)

Default: [ ]

Declared by:

services.podman.containers.<name>.socketActivation.*.fileDescriptorName

Name of the file descriptor that the socket should use.

Type: null or string

Default: null

Declared by:

services.podman.containers.<name>.socketActivation.*.port

Port that the socket should listen on

Type: string or 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Declared by:

services.podman.containers.<name>.stack

Stack that a container is part of. For every stack, a Podman networking will be crearted that the respective container will be connected to.

Type: null or string

Default: null

Declared by:

services.podman.containers.<name>.templateMount

Bind mount that will render the template with gomplate. The resulting file will be mounted into the container.

All environment variables from the environment and extraEnv options will be available for substitution.

See

Type: list of (submodule)

Default: [ ]

Example:

[
  {
    templatePath = pkgs.writeText "some-template" ''
      Hello {{ env.GetEnv "USER" "you" }}
      Secret Password is: {{ file.ReadFile "/run/secrets/some_secret" }}
    '';
    destPath = "/run/secrets/templated_file";
  }
]

Declared by:

services.podman.containers.<name>.templateMount.*.destPath

Destination path of the templated file within the container

Type: absolute path

Declared by:

services.podman.containers.<name>.templateMount.*.templatePath

Path to the template. The file will be templated with gomplate before being mounted.

Type: absolute path

Declared by:

services.podman.containers.<name>.traefik.middleware

A mapping of middleware name to a boolean that indicated if the middleware should be applied to the service.

Type: attribute set of (submodule)

Default: { }

Declared by:

services.podman.containers.<name>.traefik.middleware.<name>.enable

Whether the middleware should be applied to the service

Type: boolean

Default: false

Declared by:

services.podman.containers.<name>.traefik.middleware.<name>.order

Order of the middleware. Middlewares will be called in order by Traefik. Lower number means higher priority.

Type: signed integer

Default: 1000

Declared by:

services.podman.containers.<name>.traefik.name

The name of the service as it will be registered in Traefik. Will be used as a default for the subdomain.

If not set (null), the service will not be registered in Traefik.

Type: null or string

Default: null

Declared by:

services.podman.containers.<name>.traefik.serviceAddressInternal

The internal main address of the service. Can be used for internal communication without going through Traefik, when inside the same Podman network.

Type: string (read only)

Default: "${containerName}${containerCfg.port}"

Declared by:

services.podman.containers.<name>.traefik.serviceHost

The host name of the service as it will be registered in Traefik.

Type: string (read only)

Default: "${traefikCfg.subDomain}.${nps.stacks.traefik.domain}"

Declared by:

services.podman.containers.<name>.traefik.serviceUrl

The full URL of the service as it will be registered in Traefik. This will be the serviceHost including the “https://” prefix.

Type: string (read only)

Default: "https://${traefikCfg.serviceHost}"

Declared by:

services.podman.containers.<name>.traefik.subDomain

The subdomain of the service as it will be registered in Traefik.

Type: string

Default: "traefikCfg.name"

Declared by:

services.podman.containers.<name>.wants

List of systemd resources that this container depends on. Compared to dependsOn, this is a softer requirement and will setup systemd Wants and After attributes. When specifying a dependency on another container, use the option wantsContainer instead.

See

Type: list of string

Default: [ ]

Declared by:

services.podman.containers.<name>.wantsContainer

List of containers that this container depends on. Similar to dependsOn, but will automatically apply correct pre- and suffix for the generated systemd services.

Type: list of string

Default: [ ]

Declared by: