Support PUID/PGID in docker environment variables, default to 999 #21

New Issue

MrUnknownDE · 2026-04-05T16:15:36+02:00

MrUnknownDE commented

2026-04-05 16:15:36 +02:00

Originally created by @jonlivingstone on 3/29/2026

Hello, I enjoy using Databasus but I have an issue when backing up Databasus' own DB.

The Docker image creates a postgres user with an unpinned UID/GID (ends up as 100:102 on bookworm-slim), and the entrypoint runs chown -R postgres:postgres /databasus-data, resetting permissions on every restart. This makes the entire data directory inaccessible to host-level backup agents.

I'm running on TrueNAS where I cannot modify group 102 to add my backup user, and the filesystem doesn't support POSIX ACLs. I have a workaround but it forces me to have a separate file backup outside of my main filesystem backup agent.

If you find any the suggested improvements useful I'd be happy to incorporate your feedback and work on a PR.

Suggested improvements

(Disclaimer: the examples below are not tested, but here to give an idea of the scope of the change)

1. Only chown `/databasus-data/pgdata`, not the entire `/databasus-data`

Currently the entrypoint chowns all of /databasus-data to the postgres user. But only pgdata/ actually needs to be owned by postgres for PostgreSQL to function. Files like secret.key, backups/, and temp/ are used by the main Go application which runs as root — they don't need postgres ownership.

In start.sh:

# Only chown pgdata, not the entire data directory
chown -R postgres:postgres /databasus-data/pgdata
chmod 700 /databasus-data/pgdata

# Leave backups, secret.key, temp owned by root (the main process user)

This alone would solve the backup access problem for most NAS users, since the backup agent only needs to read secret.key and the backup metadata — not the raw PostgreSQL data files.

2. Pin the postgres UID/GID to 999:999

The current useradd -m -s /bin/bash postgres || true doesn't specify a UID/GID, so it gets whatever is next available in the container image (currently 100:102). This can even shift between image rebuilds if other packages add system users first.

Pinning to 999:999 would match the official postgres Docker image convention and be predictable for users:

RUN groupadd -r postgres --gid=999 && \
    useradd -r -g postgres --uid=999 -m -s /bin/bash postgres

3. Support `PUID`/`PGID` environment variables (nice-to-have)

Following the convention established by LinuxServer.io images, allow users to override the UID/GID of the main process that owns files on the mounted volume. This would let NAS users align file ownership with their host system.

Note: in Databasus' case, this would mean modifying the UID/GID of the user that owns the data files on disk, not necessarily the postgres process user. If suggestion 1 is implemented (only pgdata owned by postgres), then PUID/PGID would apply to the root/main process that owns everything else. If not, it could be applied to the postgres user via usermod/groupmod at startup:

# Create or modify the main process user
if [ -n "${PUID}" ] || [ -n "${PGID}" ]; then
    APP_USER="databasus"
    APP_UID="${PUID:-0}"
    APP_GID="${PGID:-0}"
    groupadd -o -g "${APP_GID}" "${APP_USER}" 2>/dev/null || true
    useradd -o -u "${APP_UID}" -g "${APP_GID}" -m "${APP_USER}" 2>/dev/null || true
    chown -R "${APP_UID}:${APP_GID}" /databasus-data/*
    exec gosu "${APP_USER}" ./main
else
    exec ./main
fi

NAS users typically rely on filesystem-level snapshots and backup agents that run as specific host users. When a container hard-codes file ownership to an unpredictable UID/GID and resets it on every restart, it makes it impossible to grant backup access through standard Unix permissions.

This affects users across NAS platforms: TrueNAS, Unraid (which runs containers as nobody:users 99:100 by default), and Synology (which layers its own DSM ACLs on top of filesystem permissions). PUID/PGID support is a well-established convention, and many self-hosted projects have received similar requests: Vaultwarden #602, Pi-hole #328, Nextcloud AIO #1974, DnsServer #1163, among others. On TrueNAS users below 568 are reserved for system use and their group membership can't be changed, to ensure stability of the system.

Suggestion (1) and (2) would solve the backup access problem for most users with minimal changes to the codebase, (3) is more a nice-to-have but could be done at the same time.

Thank you for your consideration and for this nice backup utility.

*Originally created by @jonlivingstone on 3/29/2026* Hello, I enjoy using Databasus but I have an issue when backing up Databasus' own DB. The Docker image creates a `postgres` user with an unpinned UID/GID (ends up as 100:102 on bookworm-slim), and the entrypoint runs `chown -R postgres:postgres /databasus-data`, resetting permissions on every restart. This makes the entire data directory inaccessible to host-level backup agents. I'm running on TrueNAS where I cannot modify group 102 to add my backup user, and the filesystem doesn't support POSIX ACLs. I have a workaround but it forces me to have a separate file backup outside of my main filesystem backup agent. If you find any the suggested improvements useful I'd be happy to incorporate your feedback and work on a PR. ## Suggested improvements (Disclaimer: the examples below are not tested, but here to give an idea of the scope of the change) ### 1. Only chown `/databasus-data/pgdata`, not the entire `/databasus-data` Currently the entrypoint `chown`s all of `/databasus-data` to the postgres user. But only `pgdata/` actually needs to be owned by postgres for PostgreSQL to function. Files like `secret.key`, `backups/`, and `temp/` are used by the main Go application which runs as root — they don't need postgres ownership. In `start.sh`: ```bash # Only chown pgdata, not the entire data directory chown -R postgres:postgres /databasus-data/pgdata chmod 700 /databasus-data/pgdata # Leave backups, secret.key, temp owned by root (the main process user) ``` This alone would solve the backup access problem for most NAS users, since the backup agent only needs to read `secret.key` and the backup metadata — not the raw PostgreSQL data files. ### 2. Pin the postgres UID/GID to 999:999 The current `useradd -m -s /bin/bash postgres || true` doesn't specify a UID/GID, so it gets whatever is next available in the container image (currently 100:102). This can even shift between image rebuilds if other packages add system users first. Pinning to 999:999 would match the [official postgres Docker image](https://hub.docker.com/_/postgres) convention and be predictable for users: ```dockerfile RUN groupadd -r postgres --gid=999 && \ useradd -r -g postgres --uid=999 -m -s /bin/bash postgres ``` ### 3. Support `PUID`/`PGID` environment variables (nice-to-have) Following the convention established by [LinuxServer.io images](https://docs.linuxserver.io/general/understanding-puid-and-pgid/), allow users to override the UID/GID of the main process that owns files on the mounted volume. This would let NAS users align file ownership with their host system. Note: in Databasus' case, this would mean modifying the UID/GID of the user that owns the data files on disk, not necessarily the postgres process user. If suggestion 1 is implemented (only pgdata owned by postgres), then PUID/PGID would apply to the root/main process that owns everything else. If not, it could be applied to the postgres user via `usermod`/`groupmod` at startup: ```bash # Create or modify the main process user if [ -n "${PUID}" ] || [ -n "${PGID}" ]; then APP_USER="databasus" APP_UID="${PUID:-0}" APP_GID="${PGID:-0}" groupadd -o -g "${APP_GID}" "${APP_USER}" 2>/dev/null || true useradd -o -u "${APP_UID}" -g "${APP_GID}" -m "${APP_USER}" 2>/dev/null || true chown -R "${APP_UID}:${APP_GID}" /databasus-data/* exec gosu "${APP_USER}" ./main else exec ./main fi ``` NAS users typically rely on filesystem-level snapshots and backup agents that run as specific host users. When a container hard-codes file ownership to an unpredictable UID/GID and resets it on every restart, it makes it impossible to grant backup access through standard Unix permissions. This affects users across NAS platforms: TrueNAS, Unraid (which runs containers as nobody:users 99:100 by default), and Synology (which layers its own DSM ACLs on top of filesystem permissions). PUID/PGID support is a well-established convention, and many self-hosted projects have received similar requests: [Vaultwarden #602](https://github.com/dani-garcia/vaultwarden/issues/602), [Pi-hole #328](https://github.com/pi-hole/docker-pi-hole/issues/328), [Nextcloud AIO #1974](https://github.com/nextcloud/all-in-one/discussions/1974), [DnsServer #1163](https://github.com/TechnitiumSoftware/DnsServer/issues/1163), among others. On TrueNAS users below 568 are reserved for system use and their group membership can't be changed, to ensure stability of the system. Suggestion (1) and (2) would solve the backup access problem for most users with minimal changes to the codebase, (3) is more a nice-to-have but could be done at the same time. Thank you for your consideration and for this nice backup utility.

MrUnknownDE closed this issue

2026-04-05 16:15:36 +02:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/databasus#21

Support PUID/PGID in docker environment variables, default to 999 #21

Suggested improvements

1. Only chown /databasus-data/pgdata, not the entire /databasus-data

2. Pin the postgres UID/GID to 999:999

3. Support PUID/PGID environment variables (nice-to-have)

1. Only chown `/databasus-data/pgdata`, not the entire `/databasus-data`

3. Support `PUID`/`PGID` environment variables (nice-to-have)