5.2 KiB
Local game templates
The local template directory is ${DOGAMA_DATA_PATH:-./data}/templates on the Docker host and /var/lib/dogama/templates inside the application container. The production Compose file already persists it through the existing DoGaMa data bind mount; no extra environment variable or container privilege is required.
At first start, official templates packaged in the DoGaMa image are copied into this directory. The copy is fill-only: a template or asset that already exists locally is never overwritten. This protects administrator customizations across restarts and image updates. Remove a local template directory yourself only when you intentionally want to remove it, then use Catalog → Scan.
Managing templates
Use one direct child directory per game:
./data/templates/
palworld/
template.yaml
assets/
Add or edit files on the Docker host, then sign in as an administrator and press Scan in Catalog. The scan reads each directory independently, validates it, updates changed templates and removes deleted templates from the available catalog. A broken template never prevents other valid templates from appearing. The result lists the directory name and a safe validation reason; it intentionally does not disclose absolute host paths, stack traces or secrets.
Template format
Templates use schema version 1 and are strict YAML documents. Existing deployment fields remain required: container image/tag, ports, storage mounts, configuration fields, capabilities, backup, healthcheck, imports, updates and compatibility. DoGaMa rejects unknown fields and unsafe paths, asset checksums, invalid configuration fields and invalid Docker-related declarations; a template cannot grant arbitrary Docker access.
The catalog information is under game and requirements:
schema_version: 1
id: example-game
version: 1.0.0
source: { type: local }
game:
id: example-game
name: Example Game
description: Concise dedicated-server description.
image: https://example.invalid/cover.jpg # vertical public cover URL
artwork:
logo: assets/icon.png # retained deployment artwork asset
image: assets/banner.jpg
attribution: Your attribution text
requirements:
minimum: { cpu_cores: 2, memory_mb: 4096, storage_gb: 20, other: ["Network connection"] }
recommended: { cpu_cores: 4, memory_mb: 8192, storage_gb: 40 }
game.image is the vertical cover displayed by Catalog and the game page. Its URL must be HTTPS, but validation never fetches it: an unavailable remote cover does not block a scan and the interface has a graphical fallback. requirements.minimum and requirements.recommended contain generic CPU, memory and storage values plus optional other lines. Recommended resources cannot be below minimum resources.
configuration.fields drives the deployment form and the effective server configuration. Supported types are string, integer, number, boolean, enum and secret; defaults, required flags, numeric bounds, regular expressions and enum values are checked again by the server. Secret inputs are write-only, encrypted in the instance secret store when retained for runtime use, and never included in a persisted preview, API response, audit event or error.
Each field has one explicit target. environment uses name as a container environment-variable name; static container.environment values are retained and a field may only set its own declared target. DOGAMA_* and process/internal variables are protected. argument uses name as an argv prefix: ordinary values become name=value; boolean fields emit a flag only when true, unless name contains {{value}}, in which case it is substituted for both boolean values. Arguments are passed as Docker argv entries, never through a shell.
An ini target is constrained to a writable declared storage mount and needs mount, a relative file, section and key (with name retained as its display identifier):
target:
kind: ini
name: ServerName
mount: saved
file: Config/LinuxServer/PalWorldSettings.ini
section: /Script/Pal.PalGameWorldSettings
key: ServerName
Absolute paths, traversal and symlinked parent directories are refused. INI changes preserve unrelated sections and keys and use a same-directory temporary file plus atomic rename.
Administrators deploy from Catalog → game → Deploy. The visible instance name is converted deterministically to the safe technical slug used for mount paths (for example Été / Serveur #2 becomes ete-serveur-2). DoGaMa derives every mount below its configured server root, validates a canonical preview and asks only the restricted agent to create and start the container.
When the template supports imports, the form accepts ZIP, TAR, TAR.GZ and TAR.ZST save archives. Uploads are size-bounded, staged under the configured import root with generated names, checked for traversal and expected save layout. Deployment order is install (stopped) → import → apply resolved configuration → start, so DoGaMa form values intentionally take priority over configuration files present in an imported save. Invalid staging data is removed and a configuration failure prevents startup.