# 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:

```text
./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`:

```yaml
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):

```yaml
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`.