DoGaMa

DoGaMa is a lightweight, self-hosted manager for private game servers running as Docker containers. It is designed for families and small groups of friends, not for commercial hosting or general Docker administration.

This repository currently contains the normative product and engineering specification. Implementation must follow the documents and machine-readable contracts linked below.

Product invariants

• DoGaMa only displays and operates game-server containers that it created or explicitly adopted through a controlled administrator workflow.
• The main application never mounts the Docker socket. A separate, private, restricted agent is the only component allowed to reach Docker.
• The main application is a small Go service with an embedded web UI and SQLite.
• Game-specific integrations are exclusively lightweight WebAssembly adapters. They never run as privileged host processes or sidecar containers.
• A module may contact only the API endpoint of its assigned instance, through host-provided functions and declared ports.
• Templates are declarative, versioned YAML documents validated against a JSON Schema.
• Almost all operational configuration is performed in the web interface. compose.yaml only bootstraps DoGaMa itself.
• Secrets are never returned after submission, logged, audited, or included in normal exports.
• Destructive operations preserve player data and backups by default.

Documentation map

Product

• Vision and scope
• V1 acceptance criteria
• Roadmap

Architecture and domain

• System architecture
• Main application
• Restricted Docker agent
• WebAssembly module runtime
• Data model
• Roles and permissions
• Instance lifecycle

Operations and security

• Backups, import, restore and export
• Resources, ports, storage, mods and updates
• Notifications and audit
• Security and threat model
• Administration and manager interfaces

Contributor contracts

• Current operational project state
• Development conventions
• AI and Codex contributor guide
• Template schema
• Module manifest schema
• Normalized module API
• Palworld reference template
• Palworld reference module manifest

Intended deployment

Browser
   |
   v
DoGaMa main application ---- SQLite / catalog / backups
   |
   | private authenticated API
   v
Restricted Docker agent ---- Docker socket
   |
   v
Managed game-server containers

Only the main application's HTTP port is published. The agent and game-management APIs remain on private Docker networks. Individual game ports are published by the managed instances according to approved templates and administrator configuration.

Status

The first seven roadmap foundations are implemented: application/authentication, the restricted agent boundary, the validated catalog, registered instance lifecycle, per-instance authorization, recoverable game-data backups, and the WebAssembly integration runtime. DoGaMa creates atomic tar.zst archives with manifests and SHA-256 metadata, selectively retains scheduled backups, supports five-field cron policies with IANA timezones, stages hostile imports under strict limits, and restores through validated staging with a default pre_restore safety backup. The module runtime executes typed, capability-checked adapters with bounded resources and instance-pinned networking; the bundled Palworld REST reference adapter is compiled reproducibly and covered by sandbox integration tests. Updates remain later roadmap work.

Validate the specification

Install the temporary validation dependencies from tools/requirements-validation.txt, then run python tools/validate_spec.py. The check validates both JSON Schemas, YAML examples, cross-referenced ports/mounts/capabilities, packaged-asset checksums, JSON fixtures, requirement coverage and internal Markdown links.