docker!: switch to puid/guid runtime user mapping

Author: Ravinou

.env.sample

@@ -8,17 +8,18 @@ SSH_SERVER_PORT=2222
 FQDN=your.domain.com
 NEXTAUTH_URL=https://your.domain.com
 
-# Secrects
+# Secrets
 NEXTAUTH_SECRET=your-secret
 CRONJOB_KEY=your-other-secret
 
-# UID:GID must match the user and group ID of the host folders and must be > 1000
-# If you want to use a different user than 1001:1001, you must rebuild the image yourself.
-UID=1001
-GID=1001
+# PUID/PGID: UID and GID the app will run as inside the container.
+# Must match the owner of your volume directories on the host.
+# Must be > 0 (root is not allowed).
+PUID=1000
+PGID=1000
 
 # Config and data folders (volume mounts)
-# The host folders must be owned by the user with UID and GID specified above
+# The host folders must be owned by the user with PUID and PGID specified above
 CONFIG_PATH=./config
 SSH_PATH=./ssh
 SSH_HOST=./ssh_host

Dockerfile

@@ -1,6 +1,3 @@
-ARG UID=1001
-ARG GID=1001
-
 FROM node:22-bookworm-slim as base
 
 # build stage
@@ -33,18 +30,18 @@ RUN pnpm run build
 # run stage
 FROM base AS runner
 
-ARG UID
-ARG GID
-
 ENV NODE_ENV production
 ENV HOSTNAME=
 
 RUN echo 'deb http://deb.debian.org/debian bookworm-backports main' >> /etc/apt/sources.list
 RUN apt-get update && apt-get install -y \
-    supervisor curl jq jc borgbackup/bookworm-backports openssh-server && \
+    supervisor curl jq jc borgbackup/bookworm-backports openssh-server gosu && \
     apt-get clean && rm -rf /var/lib/apt/lists/*
 
-RUN groupadd -g ${GID} borgwarehouse && useradd -m -u ${UID} -g ${GID} borgwarehouse
+# Remove the default 'node' user (UID 1000) to avoid conflicts with PUID=1000
+RUN userdel -r node 2>/dev/null || true
+
+RUN groupadd -g 1001 borgwarehouse && useradd -m -u 1001 -g 1001 borgwarehouse
 
 RUN cp /etc/ssh/moduli /home/borgwarehouse/
 
@@ -58,7 +55,8 @@ COPY --from=builder --chown=borgwarehouse:borgwarehouse /app/.next/static ./.nex
 COPY --from=builder --chown=borgwarehouse:borgwarehouse /app/docker/supervisord.conf ./
 COPY --from=builder --chown=borgwarehouse:borgwarehouse /app/docker/sshd_config ./
 
-USER borgwarehouse
+# Container starts as root to handle PUID/PGID remapping at runtime.
+# The entrypoint drops to borgwarehouse before starting the app.
 
 EXPOSE 3000 22
 

docker-compose.yml

@@ -5,11 +5,7 @@ services:
     #build:
     #   context: .
     #   dockerfile: Dockerfile
-    #   args:
-    #       - UID=${UID}
-    #       - GID=${GID}
     image: borgwarehouse/borgwarehouse
-    user: '${UID:?UID variable missing}:${GID:?GID variable missing}'
     ports:
       - '${WEB_SERVER_PORT:?WEB_SERVER_PORT variable missing}:3000'
       - '${SSH_SERVER_PORT:?SSH_SERVER_PORT variable missing}:22'
@@ -20,7 +16,7 @@ services:
       - ${SSH_PATH:?SSH_PATH variable missing}:/home/borgwarehouse/.ssh
       - ${SSH_HOST:?SSH_HOST variable missing}:/etc/ssh
       - ${BORG_REPOSITORY_PATH:?BORG_REPOSITORY_PATH variable missing}:/home/borgwarehouse/repos
-  # Apprise is used to send notifications, it's optional. http://apprise:8000 is the URL to use in BorgWarehouse.
+  # Apprise is used to send notifications, it's optional. http://apprise:8000 is the URL to use in BorgWarehouse.
   apprise:
     container_name: apprise
     image: caronc/apprise

docker/docker-bw-init.sh

@@ -2,17 +2,55 @@
 
 set -e
 
+PUID=${PUID:-1000}
+PGID=${PGID:-1000}
+
 SSH_DIR="/home/borgwarehouse/.ssh"
 AUTHORIZED_KEYS_FILE="$SSH_DIR/authorized_keys"
 REPOS_DIR="/home/borgwarehouse/repos"
+CONFIG_DIR="/home/borgwarehouse/app/config"
+
+print_green() { echo -e "\e[92m$1\e[0m"; }
+print_red()   { echo -e "\e[91m$1\e[0m"; }
+
+# 1. Remap borgwarehouse to PUID:PGID
+
+remap_user() {
+  if [ "$PUID" -eq 0 ] || [ "$PGID" -eq 0 ]; then
+    print_red "[ERROR] PUID and PGID cannot be 0. Running the app as root is not allowed."
+    exit 1
+  fi
 
-print_green() {
-  echo -e "\e[92m$1\e[0m";
+  print_green "Mapping borgwarehouse to UID=$PUID GID=$PGID"
+  groupmod -o -g "$PGID" borgwarehouse
+  usermod -o -u "$PUID" -p '*' borgwarehouse
+
+  # Chown the application directory only (never the user's volume mounts)
+  chown -R borgwarehouse:borgwarehouse /home/borgwarehouse/app
+  chown borgwarehouse:borgwarehouse /home/borgwarehouse /home/borgwarehouse/moduli
 }
-print_red() { 
-  echo -e "\e[91m$1\e[0m";
+
+# 2. Check volume is mounted and writable
+
+check_volume() {
+  local dir=$1
+  local name=$2
+
+  if [ ! -d "$dir" ]; then
+    print_red "[ERROR] Volume '$name' is not mounted. Expected path: $dir"
+    print_red "        Check the volumes section in your docker-compose.yml."
+    exit 1
+  fi
+
+  if ! gosu borgwarehouse test -w "$dir" 2>/dev/null; then
+    print_red "[ERROR] Volume '$name' ($dir) is not writable by UID=$PUID GID=$PGID."
+    print_red "        Fix on the host: chown -R $PUID:$PGID <your-host-path-for-$name>"
+    exit 1
+  fi
 }
 
+# 3. Generate SSH host keys if needed
+
 init_ssh_server() {
   if [ -z "$(ls -A /etc/ssh)" ]; then
     print_green "/etc/ssh is empty, generating SSH host keys..."
@@ -25,31 +63,19 @@ init_ssh_server() {
   fi
 }
 
-check_ssh_directory() {
-  if [ ! -d "$SSH_DIR" ]; then
-    print_red "The .ssh directory does not exist, you need to mount it as docker volume."
-    exit 1
-  else 
-    chmod 700 "$SSH_DIR"
-  fi
-}
+# 4. Setup authorized_keys
 
-create_authorized_keys_file() {
+setup_authorized_keys() {
   if [ ! -f "$AUTHORIZED_KEYS_FILE" ]; then
-    print_green "The authorized_keys file does not exist, creating..."
+    print_green "Creating authorized_keys file..."
     touch "$AUTHORIZED_KEYS_FILE"
   fi
-    chmod 600 "$AUTHORIZED_KEYS_FILE"
+  chown borgwarehouse:borgwarehouse "$SSH_DIR" "$AUTHORIZED_KEYS_FILE"
+  chmod 700 "$SSH_DIR"
+  chmod 600 "$AUTHORIZED_KEYS_FILE"
 }
 
-check_repos_directory() {
-  if [ ! -d "$REPOS_DIR" ]; then
-    print_red "The repos directory does not exist, you need to mount it as docker volume."
-    exit 2
-  else 
-    chmod 700 "$REPOS_DIR"
-  fi
-}
+# 5. Read SSH fingerprints
 
 get_SSH_fingerprints() {
   print_green "Getting SSH fingerprints..."
@@ -61,6 +87,8 @@ get_SSH_fingerprints() {
   export SSH_SERVER_FINGERPRINT_ECDSA="$ECDSA_FINGERPRINT"
 }
 
+# 6. Check secrets
+
 check_env() {
   if [ -z "$CRONJOB_KEY" ]; then
     CRONJOB_KEY=$(openssl rand -base64 32)
@@ -75,11 +103,16 @@ check_env() {
   fi
 }
 
+# Run
+
+remap_user
 check_env
+mkdir -p /run/sshd
 init_ssh_server
-check_ssh_directory
-create_authorized_keys_file
-check_repos_directory
+check_volume "$SSH_DIR"    ".ssh"
+check_volume "$REPOS_DIR"  "repos"
+check_volume "$CONFIG_DIR" "config"
+setup_authorized_keys
 get_SSH_fingerprints
 
 print_green "Successful initialization. BorgWarehouse is ready !"

docker/sshd_config

@@ -1,5 +1,5 @@
 Port 22
-PidFile /home/borgwarehouse/tmp/sshd.pid
+PidFile /run/sshd.pid
 AllowUsers borgwarehouse
 LogLevel INFO
 SyslogFacility AUTH

docker/supervisord.conf

@@ -1,5 +1,7 @@
 [supervisord]
 nodaemon=true
+user=root
+pidfile=/tmp/supervisord.pid
 logfile=/dev/stdout
 logfile_maxbytes=0
 loglevel=error
@@ -14,6 +16,7 @@ redirect_stderr=false
 
 [program:borgwarehouse]
 command=/usr/local/bin/node server.js
+user=borgwarehouse
 stdout_logfile=/dev/stdout
 stdout_logfile_maxbytes=0
 stderr_logfile=/dev/stderr