88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
# Instance lifecycle
|
|
|
|
## User-visible states
|
|
|
|
```text
|
|
draft -> installing -> stopped -> starting -> online
|
|
\-> degraded
|
|
online -> stopping -> stopped
|
|
any stable state -> backup | restore | update -> stable state
|
|
any state -> error | unknown | intervention_required
|
|
```
|
|
|
|
`container_running` is an observation, not the `online` state. Online requires the template health probe or module readiness check to succeed within its startup timeout.
|
|
|
|
The milestone-4 foundation persists each mutually exclusive action before
|
|
dispatch and keeps desired lifecycle state separate from observed Docker state.
|
|
It reconciles registered instances at application startup and periodically.
|
|
Until a template's module readiness adapter is available, a running container
|
|
whose readiness cannot be established is `degraded`, never optimistically
|
|
`online`. Docker automatic restart is disabled, so later scheduler work cannot
|
|
create an unbounded crash loop before the circuit-breaker policy is implemented.
|
|
|
|
## Creation
|
|
|
|
1. Select a validated template version.
|
|
2. Choose new world or import existing data.
|
|
3. Validate settings, secrets, ports, resources, storage and optional module.
|
|
4. If importing, upload to staging, inspect safely and show compatibility confidence.
|
|
5. Display a canonical deployment preview.
|
|
6. Persist instance intent and immutable configuration revision.
|
|
7. Ask the agent to check ports/disk and create the registered container.
|
|
8. For import, inject only validated data into the declared destination before first start.
|
|
9. Start if requested, wait for readiness and surface a precise result.
|
|
|
|
An approved installation request begins at step 2 with suggested values; it never skips administrator review.
|
|
|
|
## Start and stop
|
|
|
|
Start is idempotent. It fails clearly during conflicting operations or maintenance mode. Readiness transitions from starting to online/degraded/error based on health results.
|
|
|
|
Manual stop requests a module graceful shutdown when supported, then waits for the container to exit and uses the agent timeout as a bounded fallback. An idle automatic stop follows the backup rules:
|
|
|
|
- With `online_save`: request and confirm the in-game save, optionally archive while running if template consistency allows, then stop.
|
|
- Without `online_save`: stop the game first, then archive player data if configured.
|
|
|
|
The configurable failure policy is `abort_stop`, `stop_without_backup` or `force_stop_after_timeout`; safe default is `abort_stop` for automatic shutdown and an explicit choice for manual operations.
|
|
|
|
## Maintenance and pending changes
|
|
|
|
Maintenance mode blocks ordinary user starts and shows an administrator message while preserving manager/admin access. Settings specify `immediate` or `restart_required`; pending restart changes are applied together through a controlled container replacement. Keep a small redacted configuration history.
|
|
|
|
Docker label and image-tag changes use the same generic desired-versus-applied mechanism. `immediate` stops and replaces the container, restores its prior running/stopped intent and preserves every bind-mounted data path. `next_start` sets `container_config_pending`; the next explicit start pulls the desired image, replaces the container, clears the flag and starts it. A stopped instance remains stopped during immediate replacement.
|
|
|
|
The Docker user is selected at creation (`dogama`, `custom`, or image-defined) and is never editable afterward because changing it could invalidate persistent-file permissions. Administrators must use backup, new-instance creation and restore to change ownership deliberately; DoGaMa never performs automatic recursive `chown`.
|
|
|
|
## Crash-loop protection
|
|
|
|
Track unexpected exits. Default circuit breaker: five restarts within ten minutes disables automatic restart and moves the instance to error. Manual administrator action after diagnosis resets it. Scheduled jobs do not fight this state.
|
|
|
|
## Update
|
|
|
|
1. Resolve current and candidate image references/digests.
|
|
2. Check template/module compatibility, disk space and mod warnings.
|
|
3. Show changes and require confirmation.
|
|
4. Create a safety backup when policy requires it.
|
|
5. Gracefully stop.
|
|
6. Pull and replace through the agent using the same approved plan plus new image.
|
|
7. Start and verify readiness.
|
|
8. On failure, restore the previous container image/configuration; never restore player data automatically unless migration modified it and a documented compensation requires it.
|
|
9. If rollback is unsafe, leave stopped and notify.
|
|
|
|
Automatic game-server updates are off by default.
|
|
|
|
## Deletion
|
|
|
|
Deletion offers independent scopes:
|
|
|
|
1. container only;
|
|
2. container plus technical/cache files;
|
|
3. player data;
|
|
4. backups.
|
|
|
|
Scopes 3 and 4 are off by default, require typed-name confirmation and are audited. The agent deletes only the container; the main application performs carefully validated filesystem cleanup below allowed instance roots. Partial deletion remains visible until reconciled.
|
|
|
|
## Reconciliation
|
|
|
|
At startup and periodically, compare desired registry state with agent-inspected registered instances. Unknown Docker containers are ignored. Missing or altered managed containers become `unknown` or `intervention_required`; DoGaMa does not silently recreate or adopt them when data safety is uncertain.
|