6.5 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/
icon.png
banner.jpg
poster.jpg
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, unsafe paths, missing referenced assets, invalid configuration fields and invalid Docker-related declarations; a template cannot grant arbitrary Docker access. Asset contents are deliberately not checksum-pinned, so an administrator can maintain a local helper or configuration asset without invalidating an otherwise valid template.
For local-template upgrade compatibility, an existing asset sha256 key is accepted and ignored. New templates should omit it.
version identifies the immutable DoGaMa template snapshot. It is not the game-server release. The server image release is selected separately by container.tag; a floating tag follows that image publisher's tag policy for newly created or normally pulled instances.
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.
artwork:
logo: assets/icon.png
image: assets/banner.jpg
poster: assets/poster.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.artwork contains required local logo, horizontal image and poster assets. Validation never fetches remote artwork, so a scan remains local and deterministic. requirements.minimum and requirements.recommended contain generic CPU, memory and storage values plus optional other lines. Recommended resources cannot be below minimum resources.
Artwork paths must be relative to the template directory and must point to regular PNG/JPEG/GIF/WebP files supplied by the template. HTTP(S) URLs, absolute paths, traversal and escaping symlinks are rejected. DoGaMa serves the validated files locally, and stores them in each SQLite template snapshot so older catalog versions remain renderable.
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.
Configured template repositories
Administration → Template repositories lets administrators store a name and an HTTP(S) URL for a future template source. The URL is validated and persisted in SQLite, but it is never requested by the browser or application. Remote synchronization, Git clone/fetch, HTTP downloads, provider APIs, authentication and scheduled updates are not implemented.
Configured repositories therefore do not affect Catalog → Scan. Scan remains strictly local and reads only /var/lib/dogama/templates.