electric-cherry/docs/deployment-blueprints.md

Deployment blueprints

The Deployments page is the starting point for reusable server launches. This release adds saved blueprints, launch previews, immutable managed-file recipes, launching again from history, and clearer progress and recovery.

Create and review a launch

1. Choose Create a server on Deployments (or the deploy action on the fleet).
2. Choose the current promoted setup and select a game/map, or select a blueprint.
3. Choose Preview launch. Review the image reference, configuration sources, managed files and versions, selected map, lobby, port, and prerequisite checks.
4. Enter the Plutonium key for the displayed server ID, or reuse its saved key.
5. Choose Launch server and follow the operation to verified health.

A preview lasts 30 minutes. It neither reserves capacity nor saves a key. If another launch takes the lobby or port, submission stops before saving the key; refresh the preview and review the newly assigned ID. Refreshing a preview clears the typed key so it cannot accidentally be saved against a different lobby.

Komodo connection settings, target host, RCON configuration, config filename, lobby availability, and port availability are checked locally. These checks do not probe the host or verify game/DLC files, images, Docker volumes, firewall rules, or credentials. Container and RCON verification happen after provisioning. T6 variants retain their exact catalog slug and launch ruleset; RCON health checks verify the engine map, not the variant's start location.

Save and reuse a blueprint

Expand Make this a reusable blueprint in a launch preview and give it a name and optional description. You can save a recipe even when host configuration or available capacity blocks launching. Names are unique without regard to case.

Blueprints retain the game, map variant, image reference, composed configuration when available, generated map configuration, and matching promoted script/plugin bytes. Each blueprint is a saved recipe: saving another variation requires a new name. Credentials, lobby IDs, and ports are not copied from the source server.

Use Preview launch on a blueprint card to assign fresh capacity. Remove a blueprint from the library when it is no longer needed; its existing servers, reviewed previews, and deployment history remain intact.

On a creation detail page, Launch again opens its original recipe with the next available lobby and port. This reproduces the original managed launch files, not the server's later live state. The preview also lets you save that historical recipe as a blueprint. Older deployments without a recipe retain their history but cannot offer this action.

What is frozen

The exact managed file bytes, file hashes, version metadata, composed config, selected map, and image reference are stored in SQLite. Promotion or deletion of an artifact after preview cannot change those bytes. A submitted preview is bound to one deployment: retrying the same submission returns the original operation, including after an application restart or a lost HTTP response.

Existing API clients that omit a preview still work. Their recipes are captured when queued, before provisioning begins. Queued jobs from before this update use the promoted setup at provisioning time because they have no recorded recipe.

This is a launch snapshot, not a permanent version lock. Subsequent campaigns, betas, and drift reconciliation continue to follow the server's game/map scopes. Container tags can resolve to newer images; use a digest for a fixed image. Without a promoted baseline, Plutainer seeds its own defaults on first boot, which are not captured. Host, network, game-file volumes, destination directories, and RCON/Plutonium credentials use the environment and key store at launch time. A changed main config filename blocks reuse rather than silently loading the wrong configuration.

Recipes do not include the separately stored Plutonium or integration credentials. Managed files can themselves contain sensitive configuration, so protect database backups as you would the existing artifact library and saved-key database. Public recipe responses contain file metadata and hashes, not file contents.

Progress and interrupted operations

Creation verifies container health, then RCON, then the selected engine map. The detail page explains the current condition, displays elapsed time, and keeps its activity history. A completed container start is not reported as a completed server launch until the health checks pass.

For failed or interrupted creations, Resume health verification appears only when the original server is still registered on its assigned port and no later lifecycle operation has targeted that ID. It resumes observation only; it never recreates or restarts a container. Missing servers and later destruction attempts require inspection rather than replaying provisioning automatically.

API

• GET /api/blueprints: list summaries.
• POST /api/blueprints: save { name, description?, previewId } or { name, description?, deploymentId }.
• DELETE /api/blueprints/:id: remove a library entry.
• POST /api/deployments/preview: preview { game, mapSlug }, { blueprintId }, or { deploymentId }. Returns an ID, expiry, recipe summary, capacity, key availability (never its value), and prerequisite checks.
• POST /api/servers: existing request plus optional previewId; the game and map must match that preview. expectedName remains supported.
• GET /api/deployments/:id: includes recipe, blueprintName, and canResumeVerification for lifecycle operations.
• POST /api/deployments/:id/resume: resume eligible creation health checks.

Bulk collections, scheduled game nights, and beta-gated expansion are future layers; they are not activated by saving or launching a blueprint.