Container Options
This project extends Home Managers existing services.podman.containers options, to provide additional abstractions for example for Traefik or Homepage.
While you won't need to set any of those to get the stacks up and running, they can be useful when customizing settings.
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 list contains all extension options that will be added by this project.
services.podman.containers.<name>.alloy.enable
Alloy Log Scraping. If enabled, Alloy will scrape logs from the container and ship them to Loki.;
booleanconfig.nps.stacks.monitoring.alloy.collectByDefaultservices.podman.containers.<name>.dashboard
Metadata shared between the dashboards. Settings that only apply to a single dashboard go into its own container option.
services.podman.containers.<name>.dashboard.category
Category of the service, null hides it.
services.podman.containers.<name>.dashboard.description
Short description of the service.
services.podman.containers.<name>.dashboard.icon
Icon in Glance syntax, translated for Homepage.
di:name becomes name, sh:name becomes sh-name, a bare name
is resolved via dashboard-icons.
null or stringnull"di:jellyfin"services.podman.containers.<name>.dashboard.id
Identifier of the service, referenced by the parent of its child containers.
Defaults to the container name.
services.podman.containers.<name>.dashboard.name
Name of the service on the dashboards.
stringlib.toSentenceCase "<container name>"services.podman.containers.<name>.dashboard.parent
Identifier of the service this container belongs to.
Groups it below the parent on the dashboard and keeps it off Homepage,
set homepage.category to show it there anyway.
services.podman.containers.<name>.dashboard.url
URL the service links to, defaults to the Traefik serviceUrl.
null or stringconfig.traefik.serviceUrlservices.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
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.
services.podman.containers.<name>.dynacat
Settings for the service.
See https://dynacat.artur.zone/#configuration/docker-containers
open submodule of (YAML 1.1 value){ }services.podman.containers.<name>.dynacat.category
Category of the service, null hides it on Dynacat.
services.podman.containers.<name>.dynacat.name
The name of the service as it will displayed on the dashboard.
services.podman.containers.<name>.dynacat.url
The URL of the service.
services.podman.containers.<name>.environment
This option has no description.
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.
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.
attribute set of (null or boolean or signed integer or string or absolute path or (submodule)){ }{
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";
}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.
attribute set of (absolute path or (submodule)){ }{
API_KEY_FILE = {
destPath = "/app/config/api-key.txt";
sourcePath = "/secrets/api-key.txt";
};
DB_PASSWORD_FILE = "/run/secrets/db-password.txt";
}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/
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.
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
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
list of string[ containerCfg.traefik.serviceHost ]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
services.podman.containers.<name>.forwardAuth.rules.*.methods
Critera matching the HTTP request method.
See https://www.authelia.com/configuration/security/access-control/#methods
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
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
one of "", "deny", "bypass", "one_factor", "two_factor"""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
services.podman.containers.<name>.forwardAuth.rules.*.subject
Criteria that matches the subject.
See https://www.authelia.com/configuration/security/access-control/#subject
list of (string or list of string)[ ]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.
services.podman.containers.<name>.gatus.enable
Whether to enable gatus.
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
services.podman.containers.<name>.glance
Settings for the service.
See https://github.com/glanceapp/glance/blob/main/docs/configuration.md#docker-containers
open submodule of (YAML 1.1 value){ }services.podman.containers.<name>.glance.category
Category of the service, null hides it on Glance.
services.podman.containers.<name>.glance.name
The name of the service as it will displayed on the dashboard.
services.podman.containers.<name>.glance.url
The URL of the service.
services.podman.containers.<name>.homepage.category
Category of the service, null hides it on Homepage.
Containers with a dashboard.parent are hidden by default.
null or stringconfig.dashboard.categoryservices.podman.containers.<name>.homepage.name
The name of the service as it will appear on the Homepage dashboard.
services.podman.containers.<name>.homepage.settings
Settings for the Homepage service. This can include widget configuration, rank and so on.
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
null or string or signed integernullservices.podman.containers.<name>.sablier
Sablier labels for the container. Must use the systemd style label names. The labels will be provided in the [X-Sablier] section of the unit file for the container.
open submodule of attribute set of string{ }services.podman.containers.<name>.sablier.enable
Whether to enable Sablier integration.
services.podman.containers.<name>.sablier.group
Group the container belongs to.
For details see https://sablierapp.dev/concepts/groups/
services.podman.containers.<name>.sablier.middleware
Options for the Traefik Sablier middleware of this container's group.
All containers of a group share one middleware. Their settings are merged: attribute sets recursively, lists as a union, other values with the last one winning.
For details see https://plugins.traefik.io/plugins/69104ac3b7d4dd76110a1a09/sablier
attribute set of (YAML 1.1 value){ }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
services.podman.containers.<name>.socketActivation.*.fileDescriptorName
Name of the file descriptor that the socket should use.
services.podman.containers.<name>.socketActivation.*.port
Port that the socket should listen on
string or 16 bit unsigned integer; between 0 and 65535 (both inclusive)services.podman.containers.<name>.socketProxyPermissions
Regex allowlists for socket-proxy access, one list per HTTP method.
Generates one label per pattern, e.g. socket-proxy.allow.get and
socket-proxy.allow.get.1. See nps.stacks.socket-proxy.sections.
attribute set of list of string{ }{
GET = [config.nps.stacks.socket-proxy.sections.containers];
POST = [config.nps.stacks.socket-proxy.sections.build "some custom regex"];
}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.
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
list of (submodule)[ ][
{
templatePath = pkgs.writeText "some-template" ''
Hello {{ env.GetEnv "USER" "you" }}
Secret Password is: {{ file.ReadFile "/run/secrets/some_secret" }}
'';
destPath = "/run/secrets/templated_file";
}
]services.podman.containers.<name>.templateMount.*.chown
Optional user and group that should own the templated file inside the container.
This will run run podman unshare chown <user:group> <destPath> on the templated file.
services.podman.containers.<name>.templateMount.*.chown.group
Group that should own the file
services.podman.containers.<name>.templateMount.*.chown.user
User that should own the file
services.podman.containers.<name>.templateMount.*.destPath
Destination path of the templated file within the container
services.podman.containers.<name>.templateMount.*.templatePath
Path to the template. The file will be templated with gomplate before being mounted.
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.
attribute set of (submodule){ }services.podman.containers.<name>.traefik.middleware.<name>.enable
Whether the middleware should be applied to the service
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.
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.
services.podman.containers.<name>.traefik.rule
Traefik router rule.
string"Host(`${traefikCfg.serviceHost}`)"services.podman.containers.<name>.traefik.scheme
Scheme Traefik uses to talk to the service.
Use h2c for backends that speak HTTP/2 in clear text, such as gRPC servers.
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.
If the container shares another container's network namespace (e.g. via network = ["container:gluetun"]),
the address of that container is used instead
string"${containerName}:${containerCfg.port}"services.podman.containers.<name>.traefik.serviceHost
The host name of the service as it will be registered in Traefik.
string"${traefikCfg.subDomain}.${nps.stacks.traefik.domain}"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.
string"https://${traefikCfg.serviceHost}"services.podman.containers.<name>.traefik.subDomain
The subdomain of the service as it will be registered in Traefik.
services.podman.containers.<name>.volumeMap
Attribute set of named volume mappings.
This is just a wrapper of the volumes option, that allows defining volume mappings using an attrset.
The stack modules will use the volumeMap to set volume mappings for the container. This allows overriding specific
volume mappings without having to redefine the entire volumes list.
attribute set of string{ }{
config = "/host/bar/config:/config";
db = "/host/foo/db:/db";
}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
services.podman.containers.<name>.wantsContainer
List of containers that this container depends on.
Similar to wants, but will automatically apply correct pre- and suffix for
the generated systemd services.