feat: add PUID and GUID (#82)

dgibbs64 · web-flow · commit b9e930896e14 · 2025-08-18T19:36:06.000+01:00
* feat(docker): add configurable user and group IDs for non-root user

* Introduced `ARG PUID` and `ARG PGID` to allow customization of user and group IDs.
* Updated user creation command to use these arguments for better flexibility.

* feat(dockerfiles): add bootstrap step for SteamCMD

* Added a `RUN steamcmd +login anonymous +quit || true` command to bootstrap SteamCMD in the Dockerfiles for Ubuntu 20.04, 22.04, and 24.04.
* This ensures that SteamCMD is properly initialized during the image build process.

* feat(readme): update tags section with support details

* Enhanced the `Tags` section to include detailed support information for each Ubuntu release.
* Added notes on standard support end dates and legacy support for older versions.
* Improved clarity on the usage of the Docker image and data persistence instructions.

* feat(docker): enhance Dockerfiles and add entrypoint script

* Added `gosu` to Dockerfiles for better user switching.
* Updated user creation and command execution to run as the `steam` user.
* Introduced `docker-entrypoint.sh` to handle UID/GID adjustments at runtime.
* Modified README to clarify app installation instructions and data persistence.

* fix(readme): correct volume mount syntax in usage examples

* Updated volume mount paths in the README to use consistent quoting.
* Ensures clarity and correctness for users running Docker commands.

* docs: update README to move Notes section

* Moved the Notes section to the end of the document for better organization.
* Clarified the container's basis on the `steamcmd` container and its primary use for `LinuxGSM` game servers.

* fix(readme): correct GitHub Actions workflow link

* Updated the GitHub Actions workflow link in the README to reflect the correct path.
diff --git a/Dockerfile.ubuntu-2004 b/Dockerfile.ubuntu-2004
@@ -1,6 +1,8 @@
 FROM ubuntu:20.04
 
 ARG DEBIAN_FRONTEND=noninteractive
+ARG PUID=1000
+ARG PGID=1000
 ARG BUILD_DATE
 ARG VCS_REF
 
@@ -29,6 +31,7 @@ RUN echo "**** Install SteamCMD ****" \
   libsdl2-2.0-0:i386 \
   tzdata \
   steamcmd \
+  gosu \
   && ln -s /usr/games/steamcmd /usr/bin/steamcmd \
   && locale-gen en_US.UTF-8 \
   && apt-get -y autoremove \
@@ -39,5 +42,20 @@ RUN echo "**** Install SteamCMD ****" \
 # Add unicode support
 ENV LANG=en_US.UTF-8
 
-ENTRYPOINT ["steamcmd"]
+# Create non-root user (default IDs; can be adjusted at runtime by entrypoint)
+RUN groupadd -g "${PGID}" steam \
+  && useradd -l -u "${PUID}" -g steam -m -d /home/steam -s /bin/bash steam \
+  && mkdir -p /home/steam/Steam \
+  && chown -R steam:steam /home/steam
+
+WORKDIR /home/steam
+
+# Bootstrap SteamCMD as steam user
+RUN su -s /bin/bash - steam -c 'steamcmd +login anonymous +quit || true'
+
+# Copy entrypoint
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
 CMD ["+help", "+quit"]
diff --git a/Dockerfile.ubuntu-2204 b/Dockerfile.ubuntu-2204
@@ -1,6 +1,8 @@
 FROM ubuntu:22.04
 
 ARG DEBIAN_FRONTEND=noninteractive
+ARG PUID=1000
+ARG PGID=1000
 ARG BUILD_DATE
 ARG VCS_REF
 
@@ -29,6 +31,7 @@ RUN echo "**** Install SteamCMD ****" \
   libsdl2-2.0-0:i386 \
   tzdata \
   steamcmd \
+  gosu \
   && ln -s /usr/games/steamcmd /usr/bin/steamcmd \
   && locale-gen en_US.UTF-8 \
   && apt-get -y autoremove \
@@ -39,5 +42,20 @@ RUN echo "**** Install SteamCMD ****" \
 # Add unicode support
 ENV LANG=en_US.UTF-8
 
-ENTRYPOINT ["steamcmd"]
+# Create non-root user (default IDs; can be adjusted at runtime by entrypoint)
+RUN groupadd -g "${PGID}" steam \
+  && useradd -l -u "${PUID}" -g steam -m -d /home/steam -s /bin/bash steam \
+  && mkdir -p /home/steam/Steam \
+  && chown -R steam:steam /home/steam
+
+WORKDIR /home/steam
+
+# Bootstrap SteamCMD as steam user
+RUN su -s /bin/bash - steam -c 'steamcmd +login anonymous +quit || true'
+
+# Copy entrypoint
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
 CMD ["+help", "+quit"]
diff --git a/Dockerfile.ubuntu-2404 b/Dockerfile.ubuntu-2404
@@ -4,6 +4,8 @@ FROM ubuntu:24.04
 RUN touch /var/mail/ubuntu && chown ubuntu /var/mail/ubuntu && userdel -r ubuntu
 
 ARG DEBIAN_FRONTEND=noninteractive
+ARG PUID=1000
+ARG PGID=1000
 ARG BUILD_DATE
 ARG VCS_REF
 
@@ -32,6 +34,7 @@ RUN echo "**** Install SteamCMD ****" \
   libsdl2-2.0-0:i386 \
   tzdata \
   steamcmd \
+  gosu \
   && ln -s /usr/games/steamcmd /usr/bin/steamcmd \
   && locale-gen en_US.UTF-8 \
   && apt-get -y autoremove \
@@ -42,5 +45,20 @@ RUN echo "**** Install SteamCMD ****" \
 # Add unicode support
 ENV LANG=en_US.UTF-8
 
-ENTRYPOINT ["steamcmd"]
+# Create non-root user (default IDs; can be adjusted at runtime by entrypoint)
+RUN groupadd -g "${PGID}" steam \
+  && useradd -l -u "${PUID}" -g steam -m -d /home/steam -s /bin/bash steam \
+  && mkdir -p /home/steam/Steam \
+  && chown -R steam:steam /home/steam
+
+WORKDIR /home/steam
+
+# Bootstrap SteamCMD as steam user
+RUN su -s /bin/bash - steam -c 'steamcmd +login anonymous +quit || true'
+
+# Copy entrypoint
+COPY docker-entrypoint.sh /docker-entrypoint.sh
+RUN chmod +x /docker-entrypoint.sh
+
+ENTRYPOINT ["/docker-entrypoint.sh"]
 CMD ["+help", "+quit"]
diff --git a/README.md b/README.md
@@ -4,36 +4,213 @@
   <a href="https://developer.valvesoftware.com/wiki/SteamCMD"><img src="https://user-images.githubusercontent.com/4478206/197542699-ae13797a-78bb-4f37-81c2-d4880fd7709f.jpg" alt="SteamCMD"></a>
 <br>
 <a href="https://hub.docker.com/r/gameservermanagers/steamcmd"><img src="https://img.shields.io/docker/pulls/gameservermanagers/steamcmd.svg?style=flat-square&amp;logo=docker&amp;logoColor=white" alt="Docker Pulls"></a>
-<a href="https://github.com/GameServerManagers/docker-steamcmd/actions"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/GameServerManagers/docker-steamcmd/docker-publish.yml?style=flat-square"></a>
+<a href="https://github.com/GameServerManagers/docker-steamcmd/actions"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/GameServerManagers/docker-steamcmd/action-docker-publish.yml?style=flat-square"></a>
 <a href="https://www.codacy.com/gh/GameServerManagers/docker-steamcmd/dashboard"><img src="https://img.shields.io/codacy/grade/42d400dcdd714ae080d77fcb40d00f1c?style=flat-square&logo=codacy&logoColor=white" alt="Codacy grade"></a>
 <a href="https://developer.valvesoftware.com/wiki/SteamCMD"><img src="https://img.shields.io/badge/SteamCMD-000000?style=flat-square&amp;logo=Steam&amp;logoColor=white" alt="SteamCMD"></a>
 <a href="https://github.com/GameServerManagers/docker-steamcmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gameservermanagers/docker-steamcmd?style=flat-square" alt="MIT License"></a></p>
 
 ## About
 
-SteamCMD is a command-line version of the Steam client. It allows you to download and install games on a headless server. This container image builds daily and is available on [Docker Hub](https://hub.docker.com/r/gameservermanagers/steamcmd) as well as [GitHub Container Registry](https://github.com/GameServerManagers/docker-steamcmd/pkgs/container/steamcmd).
+SteamCMD is a command-line version of the Steam client. It allows you to download and install games/server apps on a headless server. This container image builds daily and is available on [Docker Hub](https://hub.docker.com/r/gameservermanagers/steamcmd) as well as [GitHub Container Registry](https://github.com/GameServerManagers/docker-steamcmd/pkgs/container/steamcmd).
 
 ## Tags
 
-- `latest`, `ubuntu` - Latest Ubuntu LTS release
-- `ubuntu-24.04` - Ubuntu 24.04 LTS 'Noble Numbat'
-- `ubuntu-22.04` - Ubuntu 22.04 LTS 'Jammy Jackalope'
-- `ubuntu-20.04` - Ubuntu 20.04 LTS 'Focal Fossa'
+| Tag(s)             | Ubuntu Release              | Standard Support Ends\* | Notes                              |
+| ------------------ | --------------------------- | ----------------------- | ---------------------------------- |
+| `latest`, `ubuntu` | 24.04 LTS (Noble)           | April 2029              | Current LTS                        |
+| `ubuntu-24.04`     | 24.04 LTS (Noble Numbat)    | April 2029              | Current LTS                        |
+| `ubuntu-22.04`     | 22.04 LTS (Jammy Jackalope) | April 2027              | Previous LTS                       |
+| `ubuntu-20.04`     | 20.04 LTS (Focal Fossa)     | April 2025              | Legacy (receives security updates) |
+
+\*Dates are end of standard (free) security updates per Canonical's published LTS schedule. Extended Security Maintenance (ESM) may continue beyond these dates, but images may be deprecated earlier if upstream packages (e.g. SteamCMD dependencies) become unavailable.
 
 ## Usage
 
-Docker cli
+Pull the latest image and open SteamCMD interactive prompt:
+
+```bash
+docker run -it --rm gameservermanagers/steamcmd:latest
+```
+
+Download and update an app into the current host directory (example: Garry's Mod Dedicated Server - appid 4020):
+
+```bash
+docker run -it --rm \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  -v "$PWD:/data" \
+  gameservermanagers/steamcmd:latest \
+  +force_install_dir /data +login anonymous +app_update 4020 +quit
+```
+
+## Data Persistence
+
+SteamCMD stores its own library data (manifests, depots, workshop cache) in `/home/steam/.local/share/Steam`. We use `+force_install_dir` to place the app files in its own directory. If you omit `+force_install_dir` (or put it after the first `+app_update`) the app installs under:
+
+```text
+/home/steam/.local/share/Steam/steamapps/common/<AppName>
+```
+
+Using a distinct mount (e.g. `/data`) along with `+force_install_dir /data` keeps app files seperate from the Steam library cache.
+
+### Bind Mount Example
+
+```bash
+docker run -it --rm \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  -v "$PWD:/data" \
+  -v "/path/on/host/steamcmd-app:/home/steam/.local/share/Steam" \
+  gameservermanagers/steamcmd:latest \
+  +force_install_dir /data +login anonymous +app_update 4020 +quit
+```
+
+### Docker Volume Example
 
 ```bash
-docker run -it gameservermanagers/steamcmd:latest
+docker volume create steamcmd-data
+docker volume create steamcmd-app
+docker run -it --rm \
+  -v "steamcmd-data:/data" \
+  -v "steamcmd-app:/home/steam/.local/share/Steam" \
+  gameservermanagers/steamcmd:latest \
+  +force_install_dir /data +login anonymous +app_update 4020 +quit
 ```
 
-Download Counter Strike: Global Offensive Dedicated Server to current host directory.
+## User, UID & GID (PUID / PGID)
+
+The image uses a non-root user `steam` (default UID:GID 1000:1000). You can override these IDs at runtime with environment variables `PUID` and `PGID`; the entrypoint will map the user/group before executing SteamCMD so created files match your host user.
+
+### Runtime Override (recommended)
 
 ```bash
-docker run -it -v $PWD:/data gameservermanagers/steamcmd:latest +force_install_dir /data +login anonymous +app_update 740 +quit
+docker run --rm \
+  -e PUID=1001 -e PGID=1001 \
+  -v "$PWD/steam-app:/home/steam/.local/share/Steam" \
+  -v "$PWD/server-data:/data" \
+  gameservermanagers/steamcmd:latest \
+  +force_install_dir /data +login anonymous +app_update 4020 +quit
 ```
 
+### Build-Time Defaults (optional)
+
+You can still bake alternate defaults (not required for most users):
+
+```bash
+docker build --build-arg PUID=1001 --build-arg PGID=1001 -t steamcmd:uid1001 -f Dockerfile.ubuntu-2404 .
+```
+
+### Troubleshooting permissions
+
+| Symptom                        | Cause                                               | Fix                                           |
+| ------------------------------ | --------------------------------------------------- | --------------------------------------------- |
+| Files not showing in directory | Host dir owned by different UID                     | Run with matching PUID/PGID or chown host dir |
+| Steam Guard code every run     | Sentry file not persisted (no volume or unwritable) | Mount and ensure ownership of Steam data dir  |
+| Root-owned files in host mount | Ran container with `--user root`                    | Remove `--user`; use PUID/PGID env vars       |
+
+## Login Examples
+
+SteamCMD supports anonymous and authenticated logins. Use anonymous wherever possible.
+
+### Anonymous (preferred)
+
+```bash
+docker run --rm \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  -v "$PWD/steam-app:/home/steam/.local/share/Steam" \
+  -v "$PWD/server-data:/data" \
+  gameservermanagers/steamcmd:latest \
+  +force_install_dir /data +login anonymous +app_update 4020 +quit
+```
+
+### Authenticated (username/password)
+
+Some apps (e.g. certain private branches, tools, or beta depots) require a Steam account.
+
+#### Stateless (no persistent Steam data)
+
+This will almost always trigger Steam Guard on first use and again later because nothing is persisted:
+
+```bash
+docker run --rm \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  -v "$PWD/server-data:/data" \
+  gameservermanagers/steamcmd:latest \
+  +@ShutdownOnFailedCommand 1 +force_install_dir /data \
+  +login "${STEAM_USER}" "${STEAM_PASS}" +app_update 223350 +quit
+```
+
+#### Persistent (recommended)
+
+Persist `/home/steam/.local/share/Steam` so the sentry (guard) file is cached and subsequent runs skip the code prompt.
+
+```bash
+docker run --rm \
+  -e PUID=$(id -u) -e PGID=$(id -g) \
+  -v "$PWD/steam-app:/home/steam/.local/share/Steam" \
+  -v "$PWD/server-data:/data" \
+  gameservermanagers/steamcmd:latest \
+  +@ShutdownOnFailedCommand 1 \
+  +force_install_dir /data \
+  +login "${STEAM_USER}" "${STEAM_PASS}" +app_update 223350 +quit
+```
+
+Recommendations:
+
+- Always mount persistent Steam data for authenticated workflows (see Data Persistence section) to avoid repeated Steam Guard prompts.
+- Pass credentials via environment variables or a one‑shot secret, not hard‑coded in compose files committed to source control.
+- After any Steam Guard (2FA / email) prompt, you can supply the code inline: `+login user pass CODE` (third argument) or run once interactively to cache the sentry file in the mounted Steam directory.
+- Use a dedicated throwaway account with only the required entitlements; never your main account.
+- Treat the mounted Steam data directory as sensitive (contains auth tokens / sentry files). Do not publish it.
+
+### Handling Steam Guard / 2FA
+
+1. Run interactively once with a persistent Steam data mount.
+2. Enter the code when prompted (do NOT add it to scripts).
+3. Subsequent scripted runs succeed without further prompts because the sentry file is stored.
+
+## SteamCMD Commands
+
+Common commands / flags you can chain after the image name (order matters; see notes below):
+
+| Command / Flag                                 | Purpose                                                             | Example Snippet                                |
+| ---------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------- |
+| `+login anonymous`                             | Anonymous login (most dedicated servers allow)                      | `+login anonymous`                             |
+| `+login <user> <pass>`                         | Authenticated login (needed for some apps / private betas)          | `+login myuser mypass`                         |
+| `+@NoPromptForPassword 1`                      | Suppress interactive password/guard prompts (fail fast)             | `+@NoPromptForPassword 1 +login myuser mypass` |
+| `+@ShutdownOnFailedCommand 1`                  | Abort remaining commands if one fails                               | `+@ShutdownOnFailedCommand 1`                  |
+| `+force_install_dir <path>`                    | Set target directory for app files (must come before `+app_update`) | `+force_install_dir /data`                     |
+| `+app_update <appid>`                          | Install or update an app (server / game)                            | `+app_update 896660`                           |
+| `+app_update <appid> validate`                 | Integrity check & re-download missing/corrupt files (slower)        | `+app_update 740 validate`                     |
+| `+app_status <appid>`                          | Print install status / progress (debug)                             | `+app_status 896660`                           |
+| `+app_info_update 1`                           | Refresh app info cache (used before querying details)               | `+app_info_update 1`                           |
+| `+workshop_download_item <appid> <itemid>`     | Download a specific workshop item                                   | `+workshop_download_item 4020 3418671232`      |
+| `+download_depot <appid> <depotid> <manifest>` | Fetch a specific depot/manifest (version pinning)                   | `+download_depot 90 90 402078904020789`        |
+| `+sSteamCmdForcePlatformType <os>`             | Force platform (linux / windows / macos) for content                | `+sSteamCmdForcePlatformType windows`          |
+| `+runscript <file>`                            | Execute batch of commands from script file                          | `+runscript /scripts/install.txt`              |
+| `+quit`                                        | Exit steamcmd when previous commands complete                       | `+quit`                                        |
+
+### Command Notes
+
+- Recommended order: `+@ShutdownOnFailedCommand 1 +@NoPromptForPassword 1 +force_install_dir /data +login ... +app_update <appid> validate +quit`
+- Always place `+force_install_dir` before the first `+app_update` or files go to the default library (`/home/steam/Steam/steamapps`).
+- Append `validate` sparingly; use it for initial install or when corruption is suspected.
+- Use a script file (`+runscript`) for complex multi-app workflows; each line should mirror the inline form (without shell quoting issues).
+- For workshop items, ensure the base app (server) is installed first; workshop content lands under the app's workshop directory.
+- `+download_depot` may require authenticated login and correct branch access; manifests are version-specific.
+
+## FAQ
+
+**Q: How do I find an appid?**
+Search [SteamDB](https://steamdb.info) and use the numeric App ID shown.
+
+**Q: Why do I get "Failed to connect" or SSL errors?**
+Usually transient network or firewall DPI interference. Retry, or ensure outbound TCP 27015/27036 & HTTPS ports are open.
+
+**Q: Can I run multiple updates in one container invocation?**
+Yes, either chain multiple `+app_update` commands or use a runscript file with one per line.
+
+**Q: Do I need to expose any ports?**
+No for downloading content. Game server ports are handled by the separate server container you build/run using the downloaded files.
+
 ## Notes
 
 This container is based off of the [steamcmd](https://github.com/steamcmd/docker) container and is primarily used for [LinuxGSM](https://linuxgsm.com) game servers.
diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Allow runtime override of steam user UID/GID via PUID/PGID env vars.
+# If they differ from current numeric IDs, we modify /etc/passwd & /etc/group accordingly
+# before executing steamcmd. This requires the container to start as root.
+
+CURRENT_UID="$(id -u steam)"
+CURRENT_GID="$(id -g steam)"
+DESIRED_UID="${PUID:-$CURRENT_UID}"
+DESIRED_GID="${PGID:-$CURRENT_GID}"
+
+if [[ "${DESIRED_GID}" != "${CURRENT_GID}" ]]; then
+  echo "Updating steam group GID: ${CURRENT_GID} -> ${DESIRED_GID}" >&2
+  groupmod -o -g "${DESIRED_GID}" steam
+  # Fix any files owned by old GID inside home (best effort)
+  find /home/steam -xdev -group "${CURRENT_GID}" -exec chgrp -h "${DESIRED_GID}" {} + || true
+fi
+
+if [[ "${DESIRED_UID}" != "${CURRENT_UID}" ]]; then
+  echo "Updating steam user UID: ${CURRENT_UID} -> ${DESIRED_UID}" >&2
+  usermod -o -u "${DESIRED_UID}" steam
+  find /home/steam -xdev -user "${CURRENT_UID}" -exec chown -h "${DESIRED_UID}" {} + || true
+fi
+
+# Ensure ownership of Steam data root (non-recursive check first, then minimal fix if needed)
+if [[ ! -w /home/steam ]]; then
+  echo "Warning: /home/steam not writable after UID/GID adjustment" >&2
+fi
+
+# Drop to steam user and run steamcmd
+exec gosu steam:steam steamcmd "$@"
