electric-cherry/docs/deployment-blueprints.md

# Deployment blueprints

The Deployments page is the starting point for reusable server collections. A
blueprint describes a whole lineup: for example, two Kino lobbies, one Moon lobby,
and two Town lobbies, launched together from one preview.

## Build and launch a collection

1. Choose **Create blueprint** on Deployments and name the lineup.
2. Add maps from Black Ops I or II and set the number of lobbies for each.
3. Choose **Save & preview** to review every new server ID and game port.
4. Enter each lobby's Plutonium key, or leave its field blank to reuse the key
   saved for that exact server ID.
5. Choose **Launch all N servers** and follow the collection progress page.

Blueprints support up to 40 distinct game/map selections, 1–20 lobbies per map,
and 100 servers total. The host's configured port range and existing fleet may
allow fewer. A blueprint can be saved even when there is insufficient capacity
to launch it. Each map captures its promoted managed files when added.

Use **Edit** on a blueprint card to change its name, description, maps, or lobby
counts. Existing map recipes are retained when their counts change; newly added
maps capture their current promoted setup. Already reviewed launches keep their
original lineup and file contents, including after blueprint edits or removal.
Blueprints saved by the earlier single-server release load as one-server lineups
and can be expanded directly.

A collection preview does not reserve capacity. At submission, all lobby IDs,
ports, and keys are validated again. The entire collection is then queued in one
database transaction. If any server lacks a valid key or capacity has changed,
no jobs, reservations, or key changes from that submission are committed. Refreshing
the preview clears typed keys so they cannot be applied to changed server IDs.

Submitting the same preview again returns the same collection, including after
a lost response or an application restart. Reusing the blueprint with a new
preview deliberately creates another collection with fresh available capacity.

The worker provisions servers sequentially; health verification and failures are
recorded separately for each. One failure does not undo servers already created
or prevent the rest of the queued collection from being attempted. The collection
page summarizes verified, active, and failed operations and links to every
server's timeline and recovery options. Each child links back to its collection.

## Create and review a launch

1. Choose **Single 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.

Each map in a blueprint retains the game, map variant, image reference, composed configuration
when available, generated map configuration, and matching promoted script/plugin
bytes. Credentials, lobby IDs, and ports are not copied from the source server.

Use **Launch N servers** on a blueprint card to review 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 }` for a single-server recipe, or
  `{ name, description?, entries: [{ game, mapSlug, count }] }` for a collection.
- `PUT /api/blueprints/:id`: edit `{ name, description?, entries }`. Unchanged
  game/map selections keep their saved recipes.
- `DELETE /api/blueprints/:id`: remove a library entry.
- `POST /api/deployment-collections/preview`: preview `{ blueprintId }`.
- `POST /api/deployment-collections`: atomically queue `{ previewId, keys? }`,
  where `keys` maps exact preview server IDs to optional replacement keys.
- `GET /api/deployment-collections`: list collection progress summaries.
- `GET /api/deployment-collections/:id`: collection and per-server progress.
- `POST /api/deployments/preview`: preview `{ game, mapSlug }`, `{ blueprintId }`,
  or `{ deploymentId }` for a single-server recipe. Multi-server blueprints must
  use the collection endpoint; they cannot silently launch only one entry.
  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.

Scheduled game nights and beta-gated expansion remain future layers. Collection
launches begin processing immediately after all requests are queued.