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

• 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 two roadmap foundations are implemented: the main Go binary, embedded server-rendered UI, SQLite migrations, first-administrator bootstrap, local session authentication, and the restricted agent boundary with authenticated private requests, replay defense, canonical allowed-root enforcement, authenticated local registry and bounded Docker health/disk inspection. Deployment plans, container lifecycle operations and the WebAssembly runtime 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.