DoGaMa-serv/docs/domain/instance-lifecycle.md

Instance lifecycle

User-visible states

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.

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.