83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# 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](docs/product/vision-and-scope.md)
|
|
- [V1 acceptance criteria](docs/product/acceptance-criteria.md)
|
|
- [Roadmap](docs/product/roadmap.md)
|
|
|
|
### Architecture and domain
|
|
|
|
- [System architecture](docs/architecture/system-architecture.md)
|
|
- [Main application](docs/architecture/main-application.md)
|
|
- [Restricted Docker agent](docs/architecture/docker-agent.md)
|
|
- [WebAssembly module runtime](docs/architecture/wasm-modules.md)
|
|
- [Data model](docs/domain/data-model.md)
|
|
- [Roles and permissions](docs/domain/authorization.md)
|
|
- [Instance lifecycle](docs/domain/instance-lifecycle.md)
|
|
|
|
### Operations and security
|
|
|
|
- [Backups, import, restore and export](docs/operations/backups-import-export.md)
|
|
- [Resources, ports, storage, mods and updates](docs/operations/instance-operations.md)
|
|
- [Notifications and audit](docs/operations/notifications-and-audit.md)
|
|
- [Security and threat model](docs/security/security-and-threat-model.md)
|
|
- [Administration and manager interfaces](docs/ux/interfaces.md)
|
|
|
|
### Contributor contracts
|
|
|
|
- [Current operational project state](docs/PROJECT-STATE.md)
|
|
- [Development conventions](docs/contributing/development.md)
|
|
- [AI and Codex contributor guide](docs/contributing/ai-codex-guide.md)
|
|
- [Template schema](specs/template.schema.json)
|
|
- [Module manifest schema](specs/module-manifest.schema.json)
|
|
- [Normalized module API](specs/normalized-module-api.md)
|
|
- [Palworld reference template](catalog/palworld/template.yaml)
|
|
- [Palworld reference module manifest](modules/palworld-rest/manifest.yaml)
|
|
|
|
## Intended deployment
|
|
|
|
```text
|
|
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.
|