73 lines
6.2 KiB
Markdown
73 lines
6.2 KiB
Markdown
# DoGaMa project state
|
|
|
|
Read this compact operational baseline before starting a milestone. Open detailed domain documents only when the current work affects them.
|
|
|
|
## Baseline
|
|
|
|
- Current reference: milestone 9 working branch after merged milestone 8 baseline `1e226d3`.
|
|
- Released SQLite migrations: `0001` through `0009`; never rewrite them.
|
|
- Roadmap milestones 1-9 are implemented.
|
|
|
|
## Architecture
|
|
|
|
- Go main application: HTTP API, embedded server-rendered UI, authentication/authorization, SQLite, workflows, backups and WASM runtime.
|
|
- Private restricted Go agent: sole Docker-socket owner; authenticated typed API; registered-instance and plan-digest binding; no generic Docker proxy.
|
|
- Integrations: capability-scoped WebAssembly adapters only. Palworld REST is the reference module.
|
|
- Data: SQLite plus canonical allowed server, import and backup roots. Persistent game data lives outside containers.
|
|
- Contracts: declarative YAML templates and module manifests validated against JSON Schemas; released snapshots are immutable.
|
|
|
|
## Implemented capabilities
|
|
|
|
- Bootstrap administrator, local authentication, secure sessions and CSRF protection.
|
|
- Validated embedded catalog, deterministic deployment previews and instance registry.
|
|
- Restricted instance create/inspect/start/stop/restart/delete and reconciliation.
|
|
- Per-instance memberships, overrides and installation requests with backend authorization.
|
|
- Backup scheduling/retention, safe imports, export and restore with safety backups.
|
|
- Sandboxed WASM runtime and normalized module API with Palworld reference adapter.
|
|
- Game-container configuration: global and per-instance labels, safe label variables, derived instance slug, immutable Docker-user selection, tracked/pinned image tags, immediate or deferred container recreation, and public game-icon route.
|
|
- Controlled digest-aware game updates with confirmation, policy-driven pre-update backups, readiness verification, mod warnings and automatic container-plan rollback.
|
|
- Redacted configuration history retained to the latest 10 revisions, with pinned-template revalidation and immediate or deferred rollback.
|
|
- Declarative Steam Workshop item configuration with numeric-ID validation, stable ordering and backend `mods.manage` enforcement.
|
|
- Encrypted write-only SMTP, generic HTTPS webhook and Discord channels with event filters, queued test delivery, bounded retry and redacted terminal errors.
|
|
- SSRF-resistant HTTPS webhook delivery with redirect/address revalidation, event IDs, timestamps and optional HMAC-SHA256 signatures.
|
|
- Compact allow-listed audit events for authentication and significant mutations, administrator filtering, bounded manual purge, daily retention and maximum-count enforcement.
|
|
|
|
## Durable decisions
|
|
|
|
- Editable Docker labels apply only to game-server instance containers.
|
|
- Labels on the DoGaMa application container remain Compose configuration and are never read, copied or edited by DoGaMa.
|
|
- Merge order is global labels, then instance labels; instance values win. Internal technical labels are applied last and cannot be overridden.
|
|
- `dogama.*` and `io.dogama.*` are reserved label namespaces.
|
|
- Label values support only the explicit allowlist in `internal/instance/container_config.go`; unknown variables are errors, not arbitrary templates.
|
|
- `{{game.icon_url}}` is the public icon for the game. `{{instance.slug}}` remains supported.
|
|
- Instance slugs are derived from the display name, not canonical IDs. Accents are normalized to ASCII; whitespace, `/`, punctuation and special characters become safe hyphen separators; repeated and edge hyphens are removed.
|
|
- Docker user mode is fixed at creation to DoGaMa UID/GID, custom numeric UID/GID, or image-defined user. Never perform automatic recursive ownership changes.
|
|
- A pinned image tag is an explicit mutable tag, not an immutable digest. Tracked mode follows the template's declared default tag.
|
|
- Replacement-requiring changes use the generic `container_config_pending` desired-versus-applied state. Replacements preserve bind-mounted data and prior running/stopped intent.
|
|
- The main app never gains Docker-socket access; the agent remains deny-by-default and independently validates privileged plan fields.
|
|
- Update candidates are explicit `tag@sha256:digest` references. Mutable tags alone are rejected; automatic updates remain disabled.
|
|
- Mod configuration is data-only. Provider commands, scripts and arbitrary download URLs are forbidden.
|
|
- Notification configuration is unavailable unless `DOGAMA_MASTER_KEY_FILE` contains exactly 32 bytes; ciphertext is authenticated AES-GCM and secrets are never returned by list APIs.
|
|
- Notification delivery attempts are capped at five with exponential minute-scale backoff and never determine the originating operation result.
|
|
- Audit retention defaults to 30 days and 10,000 entries; zero explicitly selects unlimited retention/count within documented bounds.
|
|
|
|
## Known limitations and debt
|
|
|
|
- Release hardening remains roadmap work.
|
|
- Scheduled backup outcomes and repeated authentication blocks are audited/logged, but broader scheduler-origin notification coverage remains intentionally limited to events emitted by implemented workflows.
|
|
- The web interface is intentionally modest; several advanced workflows are API-first.
|
|
- Linux is the deployment target. Native Windows execution of the full Go suite is blocked by Unix `Statfs` code; use Linux/WSL/CI for complete execution.
|
|
- `staticcheck`, `golangci-lint` and Python specification dependencies may not be installed on every development host; report missing tooling rather than silently skipping or installing it.
|
|
|
|
## Validation and CI
|
|
|
|
- No repository-hosted Gitea/GitHub workflow files are currently present.
|
|
- Normal completion gate for Go changes is the validation set in `AGENTS.md` on Linux.
|
|
- Specification validation is `python tools/validate_spec.py` with `tools/requirements-validation.txt` available.
|
|
- Start with package/file-specific tests, then run global tests, build, race detection, vet, static analysis and schema validation as applicable.
|
|
|
|
## Next known work
|
|
|
|
- Roadmap milestone 10: security hardening, end-to-end tests, contributor documentation and release packaging.
|
|
- Update this file at the end of every merged milestone or durable architectural change; keep it compact and remove stale statements.
|