DoGaMa-serv/docs/operations/backups-import-export.md

Backups, import, restore and export

Backup policy

Each instance supports manual backups and one V1 cron schedule using a standard five-field expression plus an IANA timezone. The UI provides common presets and a preview of upcoming runs. retention_count is the number of eligible automatic backups to retain.

V1 retention deletes oldest successful scheduled backups beyond the count. It does not silently delete manual, imported or safety backups. Failed/incomplete artifacts are cleaned by a separate short operational policy.

Consistency strategies

The template declares backup sources and one strategy:

• online_save: call the module's save_world, wait for success, then archive declared data while running if safe.
• stop_then_archive: gracefully stop, archive, then restart only if it was running before the operation.

The module only requests the game to flush state. The main application owns traversal, archive, checksum, retention and metadata.

Archive format

A DoGaMa-native backup is a tar.zst containing:

manifest.json
data/<mount-id>/...

The outer database metadata stores SHA-256, size and final path. manifest.json stores schema version, backup ID, instance/template/game versions, origin, creation time, included mount IDs, relative paths and per-file or archive integrity information. It contains no secrets.

Write to a unique temporary file, flush, compute checksum and atomically rename. Never mark a backup available before finalization.

Manual and scheduled workflow

1. Acquire the instance operation lock.
2. Check writable destination and conservative free-space estimate.
3. Reach a consistent game state according to the template.
4. Traverse only declared sources without following escaping links.
5. Build and finalize the archive.
6. Restore the prior running state if the workflow stopped it.
7. Persist success and apply retention.
8. Audit manual requests and notify configured failures/successes.

Import staging

All external data first enters:

/var/lib/dogama/imports/staging/<import-id>/

Validation enforces global and template limits for upload size, extracted size, file count, nesting and operation time. Reject absolute paths, .., Windows drive paths, NULs, device/FIFO/socket entries, hard links, and symlinks that escape staging. Extraction uses create-new semantics and never overwrites application files.

Supported formats are declared by the template. Importers handle data only; imported content is never executed.

Import modes

At instance creation

Choose new_world or import. For import, validate and preview before creating directories or a container. After the deployment plan is approved, create the instance layout and copy normalized data into declared destination mounts before first start.

Existing instance

An authorized actor may:

• validate only;
• restore once from staging without retaining the upload;
• add the validated upload to managed backups, origin imported, then optionally restore.

The preview reports detected game/type, file count, expanded size, world/player hints when safely available, destination and confidence: confirmed, probable, recognized_unknown_version or unrecognized.

Restore

1. Verify permission and recent authentication.
2. Verify archive checksum, manifest and compatibility.
3. Show overwritten destinations and compatibility confidence.
4. Create a pre_restore safety backup by default; disabling it is an administrator-only exceptional action.
5. Stop the instance gracefully.
6. Extract into a new validated sibling staging directory, not the live directory.
7. Swap or copy using a recoverable plan; preserve the previous data until success.
8. Apply required ownership within approved roots.
9. Start only if requested and verify readiness.
10. On failure, restore the previous data when safe; otherwise keep the server stopped and mark intervention required.

Export

• Backup export downloads an existing integrity-verifiable archive.
• Instance configuration export is versioned YAML containing template identity, non-secret settings, resource limits, port intent, mount categories, mods and policies. Host-specific paths may be redacted or expressed as logical roots.
• Normal exports omit passwords, tokens, API credentials, encrypted blobs, internal agent metadata and session data.
• A later explicit encrypted disaster-recovery export may be designed separately; it is not V1.

Palworld import note

The reference template recognizes dedicated-server world layouts with Level.sav and Players/. A local hosted-world import may require player identity conversion. V1 must preserve the upload, warn about this possibility and never perform undocumented silent conversion. A future game-specific data converter remains separate from the WebAssembly API adapter because modules have no filesystem access.

Implemented foundation

The V1 backup foundation persists policies, archives and import-validation records in SQLite. Manual backups, listing, integrity-checked export, restore and five-field cron policy APIs are protected by the stable instance permission identifiers. Restore and backup-policy mutation use the existing recent-session safeguard.

Until an integration module is activated, the generic engine uses the safe stop_then_archive behavior even when a template advertises online_save. The later WebAssembly milestone supplies the capability call; modules will still never traverse or archive files.

ZIP, tar, tar.gz and tar.zst imports are copied to a unique staging directory before validation. Extraction uses create-new files and rejects absolute or Windows paths, traversal, links, special files, excessive nesting, excessive file counts and expanded-size overflow. A compatible validated import can be selected in an administrator creation preview. Its normalized data is copied through a create-new sibling directory into the template-declared destination immediately before first container creation; validation itself never creates a container or writes into live player data.