79 lines
6.3 KiB
Markdown
79 lines
6.3 KiB
Markdown
# Resources, ports, storage, mods and updates
|
|
|
|
## Resources
|
|
|
|
Templates declare minimum and recommended CPU, memory and storage. The creation form suggests recommended values and warns below minimum. Administrators set Docker CPU limit, memory limit/reservation and PID limit within global guardrails. DoGaMa displays current CPU/RAM and configured limits without keeping long-term time series in V1.
|
|
|
|
Before installation, update, import or backup, estimate required disk space and compare it with configurable warning and critical free-space thresholds.
|
|
|
|
## Ports and connection address
|
|
|
|
Templates name container ports and protocol. Administrators choose host ports or accept a conflict-free suggestion. DoGaMa checks its registry and asks the agent for an availability result that does not reveal unrelated containers.
|
|
|
|
A global administrator configures the public IP address or DNS name. It is displayed with each public game port. DoGaMa does not claim to configure NAT, router forwarding or firewalls. Management/API ports default to private and never appear as player connection endpoints.
|
|
|
|
## Storage
|
|
|
|
Templates declare mount IDs, container paths, categories and whether host location is configurable. Categories include `runtime`, `configuration`, `player_data`, `mods` and `logs`. Backups include only explicitly selected persistent categories, normally player data and essential configuration.
|
|
|
|
Host paths are absolute canonical paths under configured roots. Display-name input cannot inject path separators. The UI shows technical data, player data and backup locations separately. Moving storage is an explicit stopped-instance migration with space checks, verification and rollback.
|
|
|
|
## Mods
|
|
|
|
Mod support is declarative and optional. Supported provider types may include:
|
|
|
|
- `steam_workshop` with validated numeric item IDs;
|
|
- `remote_archive` with HTTPS, checksum and SSRF protections;
|
|
- `local_upload` through safe staging;
|
|
- a future named provider with a dedicated generic implementation.
|
|
|
|
The template states destination mount, ordering, restart requirement, dependency behavior and update compatibility. Modules do not download or install mods. Mod changes can require a safety backup and always create a configuration revision.
|
|
|
|
DoGaMa clearly labels unofficial mod support and never assumes a server update is compatible with installed mods.
|
|
|
|
The V1 implementation accepts only Steam Workshop numeric item IDs when the pinned template explicitly declares that provider. It persists a normalized declarative list and rejects provider commands, scripts, arbitrary URLs and changes for templates without mod support.
|
|
|
|
## Configuration application
|
|
|
|
Each template field declares `apply: immediate` or `restart_required`. Secret fields are write-only. Validate types, ranges, patterns and conflicts on both client and server. A preview lists pending changes and whether container replacement or game restart is needed.
|
|
|
|
Keep the last 10 redacted configuration revisions by default. Rollback revalidates the old revision against the pinned template/module versions before applying it.
|
|
|
|
Every desired container or mod change creates a revision, listed newest first. Rollback never restores secrets, never changes the immutable Docker user and may be immediate or deferred until the next explicit start.
|
|
|
|
## Updates
|
|
|
|
Image updates are digest-aware. A mutable tag alone is never treated as proof that nothing changed. The UI shows current and candidate references, template release notes if available, mod warnings and whether a backup will run.
|
|
|
|
The full update sequence and rollback behavior are normative in `docs/domain/instance-lifecycle.md`. Managers may trigger only updates allowed by global/instance policy; administrators choose channels and may pin a digest. Automatic updates remain disabled by default.
|
|
|
|
The V1 API requires an explicit candidate tag and SHA-256 image digest plus confirmation. A required `pre_update` backup must finish before replacement. Readiness is bounded by the template timeout; failed replacement, start or readiness restores the prior image/configuration plan when rollback is enabled, without restoring player data.
|
|
|
|
## Game-container labels, users and tags
|
|
|
|
Administrators can define global labels for game-server containers and instance-specific overrides, one `key=value` per line. Empty lines are ignored and only the first `=` separates the key. Instance labels override global labels; DoGaMa's technical labels always win. Both `dogama.*` and `io.dogama.*` are reserved.
|
|
|
|
Values support only `{{game.name}}`, `{{game.id}}`, `{{game.icon_url}}`, `{{instance.name}}`, `{{instance.id}}`, `{{instance.slug}}` and `{{server.name}}`. Unknown or malformed variables fail validation; this is substitution, not a general template language. For example:
|
|
|
|
```text
|
|
glance.name={{instance.name}}
|
|
glance.icon={{game.icon_url}}
|
|
glance.parent=DoGaMa
|
|
```
|
|
|
|
`{{game.icon_url}}` resolves to the unauthenticated, read-only `/public/game-icons/{game-id}` route. The route serves only embedded reviewed raster content with an explicit MIME type and cache policy; it is not a public catalog or administration API.
|
|
|
|
At creation, the Docker user is either the DoGaMa process UID/GID (default), an explicitly validated numeric UID/GID, or omitted to use the image-defined user. An image without `USER` may therefore run as root. The selection is immutable after creation.
|
|
|
|
The template's declared tag is the `tracked` default. An administrator may instead select a syntactically validated `pinned` tag and later return to tracked mode. Pinned means an explicitly selected mutable tag, not a digest: publishers can republish the same tag. Manual SHA-256 digest management is outside this milestone.
|
|
|
|
Label and tag changes can apply immediately or at the next start. Immediate application disconnects players and recreates only the container; bind-mounted persistent data remains. Deferred application uses the generic `container_config_pending` state.
|
|
|
|
## Template and module updates
|
|
|
|
- Updating a catalog template creates a new immutable version; instances remain pinned.
|
|
- A migration preview compares ports, paths, settings, image and module range.
|
|
- Local copied templates are independent and are never overwritten by their origin.
|
|
- Module packages update independently and require compatibility plus connection tests before activation.
|
|
- Rollback keeps the prior template snapshot, module binary and container plan available until the new combination is verified.
|