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.
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
@ -32,75 +32,79 @@ Pull the latest image and open SteamCMD interactive prompt:
docker run -it --rm gameservermanagers/steamcmd:latest
```
Download and update a dedicated server into the current host directory (example: Garry's Mod / appid 4020):
Download and update an app into the current host directory (example: Garry's Mod Dedicated Server - appid 4020):
SteamCMD data (manifests, configs, logs etc) is stored under `/home/steam/.local/share/Steam` (owned by the non‑root `steam` user). Mount a host directory or a docker volume at that path to persist it across runs. Ensure the host path is writable by the container's UID:GID (default `1000:1000`, or your custom `PUID:PGID`). If you dont use `force_install_dir` files will be downloaded to `steamapps/common`.
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:
Common commands / flags you can chain after the image name (order matters; see notes below):
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.
- 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.
### Build-Time Defaults (optional)
## Notes
You can still bake alternate defaults (not required for most users):
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.
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.
If you need fully non‑interactive guarded logins (CI), pre-stage the sentry file by performing step 1 locally and copying the Steam config directory into your CI secret store.
## SteamCMD Commands
## Known Pitfalls
Common commands / flags you can chain after the image name (order matters; see notes below):
- Missing `+force_install_dir` before `+app_update` causes files to land in the default Steam library instead of your intended mount.
- Running as root (by overriding user) can create permission mismatches when later running as the default `steam` user.
- Using `validate` every run significantly slows updates; reserve it for first install or suspected corruption.
- Authenticated logins without a persistent Steam data volume will continually re-trigger Steam Guard challenges.
- Workshop items for some games require the game server to read them from a specific path; double‑check game docs for any required symlinks or copy steps.
- Clock skew or wrong system time (TZ/ntp) can cause auth or SSL errors; ensure the host clock is correct.
- Over-zealous bind mounts (e.g. mounting an empty host dir over `/home/steam`) can hide required directories created during image build.
- 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.
## 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.
## FAQ
@ -181,11 +212,5 @@ Usually transient network or firewall DPI interference. Retry, or ensure outboun
**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: How do I pin a specific version?**
Use `+download_depot` with a known manifest id (from SteamDB) after installing the main app. Keep in mind manifests disappear over time.
**Q: My login works locally but not in CI. Why?**
Your sentry file (Steam Guard token) wasn't copied. Persist and supply the Steam config directory or use anonymous where allowed.
**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.
Daniel Gibbs
10 months ago