Supervisor Base Images

The tags, contents and versioning of the pingcore/supervisor-base images, and the artifact route for studios who need their own base.

repo.pingcore.io/pingcore/supervisor-base is the image to build a bring-your-own game server on. It carries the PingCore supervisor, its runtime, the tools the supervisor needs and the directory layout the contract expects, so a studio building FROM it installs nothing to satisfy the platform. Game runtimes, WINE, SteamCMD and the PingCore infrastructure certificates are not in it.

Tags

Linux, built on ubuntu:24.04:

  • repo.pingcore.io/pingcore/supervisor-base:ubuntu-24.04-<version>

Windows, built on mcr.microsoft.com/windows/servercore:

  • repo.pingcore.io/pingcore/supervisor-base:windows-ltsc2022-<version>

  • repo.pingcore.io/pingcore/supervisor-base:windows-ltsc2025-<version>

<version> is the supervisor version, currently 1.3.4. So a full reference reads repo.pingcore.io/pingcore/supervisor-base:ubuntu-24.04-1.3.4.

Channel tags

Three movable tags exist per platform for a first build and for local experiments. The channel name replaces the version:

  • ubuntu-24.04-latest, windows-ltsc2022-latest, windows-ltsc2025-latest: the current approved supervisor release. This moves when PingCore promotes a release after it has run on a canary server.

  • ubuntu-24.04-test, windows-ltsc2022-test, windows-ltsc2025-test: the release currently on the canary.

  • ubuntu-24.04-dev, windows-ltsc2022-dev, windows-ltsc2025-dev: the newest build pushed, which can be an unreleased pre-release.

A channel tag moves without notice, so an image built from one is not reproducible. Pin the version-suffixed tag in anything you ship. The older bare tags ubuntu-24.04, windows-ltsc2022 and windows-ltsc2025 are no longer updated; replace them with the -latest form.

What is in the base

Linux:

  • the supervisor tree at /node-service, with the Node.js runtime it needs

  • tini as PID 1, which forwards signals to Node and reaps the game's child processes

  • rclone, used for the CDN sync and the in-container SFTP server

  • DepotDownloader, used by the Steam depot data source

  • ca-certificates, curl, wget, unzip, zip, tar, gzip, bzip2, xz-utils, rsync, procps

  • libicu74, which the self-contained DepotDownloader build needs

  • the gameserver user, which the supervisor drops the game process to

  • the gshelper user (from 1.3.4), in the gameserver group, which the supervisor runs the SFTP server and steamcmd jobs as, so the game cannot read their passwords and logins. See Building Your Own Server Image for what it changes in your image

  • an empty /opt/game, the directory your game goes in

  • an empty /gameserver, the fallback data root used when PVC_DATA is unset

Windows:

  • the supervisor tree at C:\node-service, with the Node.js runtime it needs

  • rclone and DepotDownloader

  • the Visual C++ x64 redistributables, which the supervisor's console support links against

  • an empty C:\game, the directory your game goes in

  • an empty C:\gameserver, the fallback data root used when PVC_DATA is unset

There is no tini on Windows. node.exe is the container's root process and handles its own shutdown signals. There is no gshelper user on Windows either.

What you add

Your game files, and any runtime the game needs. The base ships none of the common game runtimes: .NET, DirectX, the legacy and x86 Visual C++ packages, Java and WINE are all absent. Install what your server actually links against in your own layer and leave the rest out, because every layer is disk on every node that runs your servers.

Do not add a USER directive and do not override ENTRYPOINT. Building Your Own Server Image explains why both break the container.

Versioning

The image tag is the supervisor version. A new supervisor capability bumps the minor version, a fix bumps the patch, and either way it is published under a new tag. A published version tag is never rebuilt.

Compatibility between your image and the platform is decided by the bootstrap payload the supervisor consumes. It is additive: a newer platform may send fields an older supervisor ignores, so an image pinned to an older base keeps working. You can read the version out of any image you have pulled:

docker inspect --format '{{index .Config.Labels "org.opencontainers.image.version"}}' <image>

Rebase onto a newer tag when you want new supervisor behaviour, and treat it as you would any other dependency bump. Verify the rebuilt image on one server before you roll it out.

Windows generations

The Windows base is published per Windows Server Core generation. A Windows container cannot run on an older host kernel, so match the generation to the Windows node pool your servers schedule onto. If you are unsure which that is, ask support before you build.

ltsc2022 exists for studios still on 2022 hosts. The PingCore fleet images are ltsc2025.

Advanced: using your own base image

This section is for studios who cannot use the PingCore base: a specific Linux distribution, a Wine layer you already maintain, or a Windows generation PingCore does not publish. You take on the supervisor's runtime yourself, so use the base image instead wherever you can.

repo.pingcore.io/pingcore/supervisor:<version> is a content-only image carrying the built supervisor tree. It is not runnable on its own.

FROM repo.pingcore.io/pingcore/supervisor:1.3.4 AS supervisor

FROM your-own-base:1.0
COPY --from=supervisor /node-service /node-service

You then have to supply what the base image would have given you:

  • Node.js 24 on the path the pinned entrypoint uses (node on Linux, C:\Program Files\nodejs\node.exe on Windows)

  • tini at /usr/bin/tini on Linux

  • rclone on the path, or SFTP and CDN sync fail

  • DepotDownloader at /usr/local/bin/DepotDownloader (C:\depotdownloader\DepotDownloader.exe on Windows) if you use the Steam depot data source

  • the Visual C++ x64 redistributables on Windows

The gameserver user is optional. The supervisor creates it at boot when the image does not have one, though shipping it keeps the uid and gid stable across rebuilds.

On Linux, add the gshelper user yourself. The supervisor never creates it, and without it SFTP and steamcmd run as gameserver, where the game can read the SFTP password. Create it after gameserver, in the gameserver group, with no login shell and a private home:

RUN useradd -m -d /home/gshelper -s /usr/sbin/nologin -g gameserver gshelper \
    && chmod 700 /home/gshelper

This needs a gameserver user in the image, so ship that one too.

The Windows artifact is published per generation as supervisor:<version>-windows-ltsc2022 and supervisor:<version>-windows-ltsc2025. Build against the one matching your base. The artifact has the same three channel tags: supervisor:latest, supervisor:dev and supervisor:test on Linux, and supervisor:windows-<generation>-latest, -dev and -test on Windows.