DoGaMa-serv/docs/operations/instance-operations.md

Resources, ports, storage, mods and updates

Instance detail page

Select an instance from the Dashboard to open /instances/<opaque-instance-id>. The identifier is a registry identifier, never a filesystem path. The page shows pinned artwork, lifecycle state and, when a validated active WASM module is reachable, only its declared live server information, metrics and players. Live player count and maximum are labelled live; a template max_players value is labelled configured when no live metric is available. The page never renders module credentials or ordinary secret values.

Administrators and members with the matching permissions can start, stop and create a manual backup. Actions submit server-rendered CSRF-protected forms and the existing lifecycle and backup services enforce state conflicts a second time. The backup list is limited to that instance and is ordered newest-first by the repository. Restore is shown only with backup.restore, requires an explicit browser confirmation, and continues to use the safety-backup restore workflow.

The Update control remains disabled until the template supplies a verified, immutable candidate_tag and candidate_digest; DoGaMa never invents an available update or browses a registry. It compares that approved reference with the persisted image: it is available, up to date, or safely unknown. Server controls are capability- and permission-gated: Announcement, Kick, Ban and Unban appear only when the active adapter declares the corresponding capability and the user has its backend-enforced permission. Player actions use stable game IDs. list_bans is optional for Unban: when available, the server renders the real banned-player selection and validates the submitted ID against a fresh runtime list before calling unban_player. Without list_bans, Unban renders a manual player-identifier field; DoGaMa validates only bounded, control-character-free input and leaves game-specific identifier validation to the module/API. An unavailable module or game leaves the rest of the page usable and exposes no fictional controls.

The player server_password is never loaded into the normal page. A global administrator can reveal it only through a CSRF-protected POST response with Cache-Control: no-store; the reveal is audited without the value. DoGaMa has no separate recent-password-confirmation primitive, so the existing authenticated administrator session is the most restrictive available flow. admin_password and module credentials cannot be revealed through this UI.

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.

There is no automatic check for an available update: DoGaMa does not consult a registry without an explicitly supplied, verified tag-and-digest candidate.

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:

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.

Administration stores separate decimal game-container defaults for UID and GID (1000:1000 initially, bounded to Linux's uint32 range). A template with the managed user_mode: dogama policy receives those values as Docker User; DoGaMa and its agent are never affected. A template with user_mode: image always omits Docker User, even if an API caller requests an override, so the image's native USER and entrypoint remain authoritative. Templates may instead declare a generic runtime_user environment mapping; V Rising uses this to receive its administrator defaults as PUID/PGID while retaining its root entrypoint and declared capabilities.

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.