68 lines
5.4 KiB
Markdown
68 lines
5.4 KiB
Markdown
# Data model
|
|
|
|
SQLite is authoritative for product state. Runtime Docker state is reconciled into, but never replaces, the registry.
|
|
|
|
## Core entities
|
|
|
|
| Entity | Purpose | Important fields |
|
|
|---|---|---|
|
|
| `users` | Local identities | id, username, password_hash, global_role, disabled_at, created_at |
|
|
| `sessions` | Revocable browser sessions | id_hash, user_id, expires_at, last_seen_at |
|
|
| `instance_memberships` | Per-instance baseline role | instance_id, user_id, role (`user`, `manager`) |
|
|
| `permission_overrides` | Explicit allow/deny beyond baseline | instance_id, user_id, permission, effect |
|
|
| `templates` | Catalog identity and origin | id, origin, trust_status, active_version |
|
|
| `template_versions` | Immutable validated snapshots | template_id, version, schema_version, canonical_yaml, digest |
|
|
| `modules` | Module identity and trust | id, source, trust_status, active_version |
|
|
| `module_versions` | Immutable installed artifacts | module_id, version, manifest, wasm_digest, path, api_range |
|
|
| `instances` | Desired and observed instance state | id, derived slug, display_name, template snapshot, revision, lifecycle_state, Docker-user mode/UID/GID, image-tag mode/tag, custom labels, container_config_pending |
|
|
| `instance_settings` | Typed non-secret template values | instance_id, field_id, value_json |
|
|
| `instance_secrets` | Encrypted secret values | instance_id, field_id, key_version, nonce, ciphertext |
|
|
| `instance_ports` | Published and private bindings | instance_id, port_id, host_ip, host_port, container_port, protocol |
|
|
| `instance_mounts` | Approved persistent mount mapping | instance_id, mount_id, host_path, container_path, category |
|
|
| `instance_resources` | Docker limits | instance_id, cpu_limit, memory_limit_mb, reservation_mb, pids_limit |
|
|
| `instance_module_bindings` | Pinned integration version | instance_id, module_id, module_version, config_revision, status |
|
|
| `configuration_revisions` | Small rollback history | instance_id, revision, redacted_snapshot, reason, created_by |
|
|
| `backup_policies` | Schedule and retention | instance_id, enabled, cron, timezone, retention_count, safety flags |
|
|
| `backups` | Managed archive metadata | id, instance_id, origin, status, path, size, sha256, game/template versions |
|
|
| `imports` | Temporary validation workflow | id, instance_id nullable, stage_path, detected_type, status, expires_at |
|
|
| `operations` | Durable long-running workflows | id, instance_id, type, phase, status, idempotency_key, error_code |
|
|
| `scheduled_jobs` | Next execution state | id, type, owner_id, schedule, timezone, next_run_at, enabled |
|
|
| `installation_requests` | User catalog requests | id, requested_by, template_id, message, status, reviewed_by |
|
|
| `notification_channels` | Global delivery configuration | id, type, enabled, encrypted_config, event_filter |
|
|
| `notification_deliveries` | Bounded retry queue | id, channel_id, event_type, payload_redacted, attempt, next_attempt_at |
|
|
| `audit_events` | Compact significant actions | id, occurred_at, actor_id, instance_id, action, outcome, summary_json |
|
|
| `system_settings` | Admin-configured global values | key, value_json, revision |
|
|
|
|
## Invariants
|
|
|
|
- IDs are opaque and stable; slugs are unique but mutable only through a controlled rename.
|
|
- Instance slugs are derived from display names, transliterated to lowercase ASCII and recalculated on rename; they are never canonical identifiers.
|
|
- The Docker-user selection is immutable after creation. Custom UID/GID values exist only for `custom`; DoGaMa never recursively changes file ownership.
|
|
- Desired container configuration is stored separately from the applied `plan_digest`; `container_config_pending` covers any replacement-requiring change without feature-specific flags.
|
|
- Released template and module versions are immutable. Editing creates a new version or an independent local copy.
|
|
- An instance pins a template snapshot and module version; catalog changes do not mutate it silently.
|
|
- There is at most one active mutating operation per instance.
|
|
- A port tuple `(host_ip scope, host_port, protocol)` cannot be assigned twice by DoGaMa.
|
|
- Mount host paths are canonical absolute paths below configured roots.
|
|
- Secret fields never coexist in plaintext settings.
|
|
- Backup metadata becomes `available` only after archive finalization and checksum persistence.
|
|
- Imports expire and their staging directories are cleaned unless attached as a managed backup.
|
|
- Audit `summary_json` is allow-listed by event type and contains no secret values or full uploaded content.
|
|
|
|
## Backup origins
|
|
|
|
`manual`, `scheduled`, `pre_update`, `pre_restore`, `idle_shutdown`, `imported` and `system` are stable origin identifiers. V1 retention applies only to automatic backups eligible under the instance policy. Manual, imported and explicit safety backups require deliberate deletion or a separately documented policy.
|
|
|
|
## Operation state
|
|
|
|
Operations use `queued`, `running`, `succeeded`, `failed`, `cancelled` or `intervention_required`. A phase-specific checkpoint records enough information to decide safely after restart whether to resume, compensate or stop.
|
|
|
|
## Data retention
|
|
|
|
- Audit: administrator-configurable, default 30 days, optional maximum entry count.
|
|
- Configuration history: default 10 revisions per instance, with secrets omitted.
|
|
- Notification delivery attempts: short operational retention after terminal state.
|
|
- Temporary imports: default 24 hours after last activity.
|
|
- Technical logs: standard output/error, outside SQLite and controlled by container log rotation.
|
|
|