Nix Podman Stacks

Appearance

Base Settings ​

Most stacks will rely on some central settings. An example would be the base location where containers should create bind mounts for persistent data.

Example ​

nix
{config, ...}: {
  nps = {
    hostIP4Address = "192.168.178.2";
    hostUid = 1000;
    storageBaseDir = "${config.home.homeDirectory}/stacks";
    externalStorageBaseDir = "/mnt/hdd";
  };
}

Options ​

nps.defaultGid ​

WARNING

Do not change this value unless you know what you are doing! You might run into permisssion issues if volumes cannot be accessed by the mapped subgid.

GID of the user that will be used by default for containers if they allow GID configuration. When running rootless containers, GID 0 gets mapped to the host users GID.

Type
plaintext
signed integer
Default
nix
0
Declaration
<nps/modules/settings.nix>

nps.defaultTz ​

Default timezone for containers. Will be passed to all containers as TZ environment variable.

Type
plaintext
null or string
Default
nix
"Etc/UTC"
Declaration
<nps/modules/settings.nix>

nps.defaultUid ​

WARNING

Do not change this value unless you know what you are doing! You might run into permisssion issues if volumes cannot be accessed by the mapped subuid.

UID of the user that will be used by default for containers if they allow UID configuration. When running rootless containers, UID 0 gets mapped to the host users UID.

Type
plaintext
signed integer
Default
nix
0
Declaration
<nps/modules/settings.nix>

nps.enableSocket ​

Whether to enable the Podman socket for user services. Note that the socket is required for the services like Traefik or Homepage to run successfully, since they access the Podman API.

If this is disabled and you use these services, you will need to manually enable the socket.

Type
plaintext
boolean
Default
nix
true
Declaration
<nps/modules/settings.nix>

nps.externalStorageBaseDir ​

Base location that will be used for larger data such as downloads or media files. Could be an external disk.

Type
plaintext
absolute path
Declaration
<nps/modules/settings.nix>

nps.hostIP4Address ​

The IPv4 address which will be used in case explicit bindings are required.

Type
plaintext
string
Declaration
<nps/modules/settings.nix>

nps.hostUid ​

UID of the host user running the containers. Will be used to infer the Podman socket location (XDG_RUNTIME_DIR).

Type
plaintext
signed integer
Default
nix
1000
Declaration
<nps/modules/settings.nix>

nps.inspection ​

Read-only, Nix-evaluated inspection data and renderings for the final Podman container configuration.

Type
plaintext
attribute set
Default
nix
{ }
Declaration
<nps/modules/inspection.nix>

nps.mediaStorageBaseDir ​

Base location for larger media files. This is where containers like Jellyfin or Immich will store their media files.

Type
plaintext
absolute path
Default
nix
"${config.nps.externalStorageBaseDir}/media"
Declaration
<nps/modules/settings.nix>

nps.package ​

The podman package to use.

Type
plaintext
package
Default
nix
pkgs.podman
Declaration
<nps/modules/settings.nix>

nps.preferHostIds ​

Whether to prefer host user mapping over subuid/subgids.

Some containers will always run with a certain UID/GID. Popular examples are Postgres, MySQL and MariaDB (999/999). When running those containers with rootless Podman, files created within volumes will be owned by subuids/subgids. While this is generally not a problem and might even be desired, it can cause issues for example in combination with NFS shares.

Enabling this option will cause the container user (e.g. 999) to be mapped to the host user. Files created by the container will then be owned be the host user running the containers. This achieved by using userns=keep-id:uid=<container-user>,gid=<container-group>.

For more infos, see https://docs.podman.io/en/stable/markdown/podman-run.1.html#userns-mode

Be aware that this option is not supported for all containers that run as a fixed user. As the userns setting will also change the init user a container is started as, it would break containers that require being started as root to chown files etc. before dropping permissions.

Type
plaintext
boolean
Default
nix
false
Declaration
<nps/modules/settings.nix>

nps.socketLocation ​

The location of the Podman socket for user services. Will be passed to containers that communicate with the Podman API, such as Traefik, Homepage or Beszel.

Type
plaintext
absolute path
Default
nix
"/run/user/${toString config.nps.hostUid}/podman/podman.sock"
Declaration
<nps/modules/settings.nix>

nps.storageBaseDir ​

Base directory for Podman storage. This is where each stack will create its bind mounts for persistent data. For example, setting this to /home/foo/stacks would result in Adguard creating its bind mount at /home/foo/stacks/adguard.

Type
plaintext
absolute path
Default
nix
"${config.home.homeDirectory}/stacks"
Declaration
<nps/modules/settings.nix>