Gametainer Catalog

Official game template catalog for Gametainer.

This repository contains the game-specific metadata that gametainer uses to create and run containerized self-hosted game servers. Templates describe how a game is installed, configured, launched, persisted, exposed on the network, and checked for readiness.

The catalog is intentionally separate from the main gametainer application so game support can evolve without requiring a new controller binary release.

Layout

catalog.yaml
index.yaml
games/
  <game>/
    definition.yaml
    settings.spec.yaml
    settings.template.yaml

• catalog.yaml describes catalog identity, compatibility, recommended image tag, release tag policy, and metadata location.
• index.yaml lists supported games and points to each game directory.
• definition.yaml defines install mode, image profile, ports, persistent paths, process launch details, lifecycle steps, readiness checks, and file-backed logs.
• settings.spec.yaml defines user-facing settings and how they map to config files or process arguments.
• settings.template.yaml is the default generated gamer config input for a game.

Local Use

From the main gametainer repository, this catalog is expected at:

../gametainer-catalog

You can override that path with:

GAMETAINER_CATALOG_ROOT=/path/to/catalog

or per command:

gametainer catalog validate --templates /path/to/catalog
gametainer games list --templates /path/to/catalog
gametainer servers create factorio my-factorio --templates /path/to/catalog

Validation

This catalog is independent of the gametainer source repository. If the gametainer CLI is installed and available on PATH, validate this checkout from the catalog root with:

gametainer catalog validate --templates .
gametainer catalog doctor --templates .
gametainer catalog doctor --templates . --baseline ../baseline-catalog

The included Justfile is only a convenience wrapper around the installed CLI:

just validate
just doctor
just doctor-baseline ../baseline-catalog
just games
just show factorio

The catalog should validate before template changes are merged. When reviewing a change against another checkout, pass that checkout as --baseline; doctor will classify medium/high-risk template changes and warn when they do not have complete changelog release and Compatibility notes.

Compatibility

The current catalog schema is v1. catalog.yaml records the minimum Gametainer version expected to consume this catalog, the recommended controller version, and the recommended image tag for the current development channel.

CI validates the catalog with the pinned Gametainer version in .gametainer-version, then runs gametainer update check --json against this checkout and fails if the selected catalog schema is not supported by that binary.

Changelog

Update CHANGELOG.md whenever template behavior changes. Use the Compatibility section for runtime support, migration policy, image profile, portability, persistent path, or operator-impacting changes.

Release Tags

Catalog releases use calendar tags:

vYYYY.MM.DD
vYYYY.MM.DD.N

Use vYYYY.MM.DD for the first catalog release on a date. Use vYYYY.MM.DD.N for same-day patches or hotfixes, for example v2026.07.02.1.

Before tagging a release:

• Set catalog.yaml and index.yaml revision to the exact Git tag.
• Move relevant CHANGELOG.md entries from Unreleased into a matching ## [vYYYY.MM.DD] or ## [vYYYY.MM.DD.N] section.
• Keep a Compatibility subsection for runtime, migration, image profile, data-portability, persistent-path, or operator-impacting changes.
• Run gametainer catalog doctor --templates . --baseline <previous-release>.

Keep revision: local-dev while the catalog is unreleased or in normal development.

The GitHub validation workflow also runs on v* tag pushes. Tag builds fail if the tag does not match vYYYY.MM.DD or vYYYY.MM.DD.N, or if index.yaml or catalog.yaml revision does not exactly match the pushed tag.

Current Templates

• factorio: archive-based Linux dedicated server.
• palworld: SteamCMD Linux dedicated server.
• valheim: SteamCMD Linux dedicated server.
• vrising: SteamCMD Windows dedicated server through Wine.

Contribution Notes

Templates should keep game-specific behavior in catalog files whenever possible. The gamer container shim and gametainer controller should remain generic.

When adding or changing a game template:

• Include source/provenance links in template metadata when available.
• Prefer normalized user-facing setting names.
• Keep defaults close to the upstream server defaults.
• Declare all required ports and persistent paths.
• Declare runtime compatibility and migration policy.
• Add readiness metadata when the server has a reliable startup signal.
• Add runtime.logs.files for important game log files, especially when a game writes useful startup or runtime output to a file instead of stdout/stderr.
• Update CHANGELOG.md with notable template changes.
• Validate the catalog before opening a pull request.

Readiness and logs are related but separate:

• runtime.readiness tells Gametainer how to decide that a server is ready.
• runtime.logs.files tells gamer which game-owned log files should be streamed or exposed through operator log commands.

If a readiness check watches a file, declare that file under runtime.logs.files as well. Current Gametainer builds keep a fallback for older templates, but explicit log metadata is the catalog contract going forward.