> For the complete documentation index, see [llms.txt](https://docs.rip.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rip.xyz/operations/indexer-deployments.md).

# Indexer deployments

Only the explicitly approved indexer serves marketplace API reads. The normal staging workflow prepares an inactive slot with its own database and then switches API approval. The normal production workflow updates the selected service against its existing database, without switching the API route or requiring a prepared standby.

A staging release normally takes a consistent snapshot of the serving database, restores it into the inactive slot, and catches up using the configured event source. Schema and indexing-history compatibility are checked before preparation. A previously verified standby resumes directly only when recent measurements predict that will be faster than copying.

Snapshot promotion requires the expected image and ECS revision, successful marketplace reads, and advancing checkpoints close to the current chain head. The API confirms its new approval before the old service stops. The old database is retained for recovery until the next swap reuses it.

## Operator choices

Use **Deploy AWS**, choose the intended environment and the indexer, and leave the slot on **auto**. The operator who dispatches the release owns monitoring and recovery until acceptance or an acknowledged handoff.

In production, dispatch from current **main** with the production gate and exact-source CI satisfied. The workflow uses `scripts/update-production-indexer.mjs`. It verifies one healthy selected writer and a fresh database/GraphQL/RPC baseline, then stops that writer before starting the exact new image against the same database. Only the indexer image may change; configuration, indexed history and API routing must match. Rebuild and baseline-adoption options are rejected. Readiness can be unavailable during replacement. Completion requires one stable writer and advancing near-head reads before dependent website publication.

In staging, a normal swap defaults to a snapshot. Select **rebuild\_indexer** for an incompatible history change. For the first migration, an operator can instead accept the serving database as the baseline using the CLI-only **ADOPT\_SOURCE\_IMAGE** option with its exact immutable image reference. This requires matching history, fresh readiness and historical RPC sample checks, and records the accepted baseline after a successful snapshot and promotion. It does not prove every earlier handler revision. The rebuild affects only the inactive slot. Ordinary restarts never reset indexed history automatically.

Snapshot activation requires the updated API, both slot services and databases, private routes, eRPC, secrets, environment-specific IAM, and a verified serving baseline. These are separate deployment steps, including for any explicitly reviewed production snapshot migration. Production bootstrap uses the authoritative flat `infrastructure/` root and must preserve the existing production RDS and services. Neither the snapshot lifecycle nor the existing-service updater bootstraps an empty environment.

## Recovery

For a production existing-service update, inspect the workflow's `indexer-swap-result.json`, the lifecycle lock and `current-service-update` under `/rip/prod/indexer/lifecycle`, the selected API reader and actual ECS tasks. Failure after a mutation or an uncertain response retains the lock and reports recovery required. There is no automatic rollback; the service can remain stopped. Reconcile the original operation before retrying or removing the lock. Restoring a prior image requires reviewed compatibility with the retained database and proof that no other writer remains. Do not reset or restore the database as a routine image rollback.

For a snapshot swap, failure before promotion keeps the serving slot approved. If a promotion response is uncertain, both services remain available for inspection. If an ECS database worker may still be running, the controller retains its lock; it never steals an expired lock automatically.

Inspect the actual API routing revision, ECS tasks, worker logs and lifecycle records before recovery. Do not clear a lock until the outstanding worker is confirmed stopped. Do not manually start, reset or redeploy a slot during a swap.

The detailed procedure, prerequisites, evidence fields and recovery checks are maintained in [the RIP deployment and recovery runbook](https://github.com/RebelDividends/hyper-rip/blob/main/docs/envio-blue-green-rollout.md). Successful workflow runs publish an `indexer-swap-result.json` artifact. Local integration tests validate snapshot consistency, RPC catch-up and reorg recovery; live staging performance must still be measured.
