Importing a standalone product into Veltro

Source of truth: docs/migration-standalone-to-suite.md (synced at build time — edit the original, not this copy). An install with one product now consists of Veltro core (gateway and identity) plus that product. It uses the same public origin and identity service as an install with all three products. The old product-only Compose profiles and their own login are no longer Veltro install options. This guide covers moving an existing VectorFlow, Sigmatic, or Warden deployment into a fresh core-plus-product install. It is a planned data and identity cutover, not a database upgrade.

Do not point the new stack at the old database or reuse its Compose volumes. The destination has its own product database and identity database. Keep source volumes and a tested backup untouched until the cutover and rollback window end. If the destination has live data, reconcile it separately; never overwrite it with a standalone dump.

Plan the destination

1. Choose the products in VELTRO_PRODUCTS in the new install’s .env, for example VELTRO_PRODUCTS=sigmatic. An empty value runs core only; leaving the selector unset installs all three. Sigmatic also needs OpenSearch. Each selected product’s database lives on the shared suite-postgres, and its Redis data on its own suite-redis index.
2. Compare the source’s applied database migrations with the image pinned in versions.env. Use a destination image that understands the source schema. If the source is ahead, stop and update the pin through the reviewed release path. A database restore is not a downgrade mechanism.
3. Inventory database rows, product file volumes, queued work and external storage. VectorFlow uses vf-data; Sigmatic uses sigmatic-data, two Redis services and OpenSearch; Warden uses warden-data and Redis. Preserve Sigmatic’s log indices with a verified OpenSearch snapshot. A PostgreSQL dump alone does not contain those assets. See backup and restore for the suite archive’s coverage and limits.
4. Back up the source, rehearse a restore in an isolated environment, and record row counts, migration heads, file checksums, index counts and queue state. Save a separate pre-import backup of the destination. Do not delete or reset a database or volume as part of this procedure.

Prepare secrets and access

Carry the product’s encryption and token secrets into the destination before starting it on imported product data. For VectorFlow this includes VF_ENCRYPTION_KEY_V2 and VF_NEXTAUTH_SECRET (the latter may also be the legacy derived encryption key). For Sigmatic it includes SIGMATIC_JWT_SECRET_KEY, SIGMATIC_SESSION_SECRET_KEY and SIGMATIC_ENCRYPTION_KEY; for Warden, WARDEN_JWT_SECRET_KEY, WARDEN_SESSION_SECRET_KEY and WARDEN_SECRET_KEY. Check the source’s actual secret configuration rather than assuming all keys were populated. Losing an encryption key can make stored credentials unrecoverable. Keep Veltro’s VELTRO_SESSION_SECRET separate; never copy a product’s session secret into it.

Product database rows do not import people, passwords, passkeys, IdP configurations or product grants into Veltro identity. Set up administrators, SSO/SCIM or users in the new identity console and assign explicit grants for each selected product. Check team grants as well as product roles. A Veltro realm administrator does not automatically receive every product grant. Existing product users are linked by the identity subject, or by email at first contact; confirm the intended account mapping before inviting users. Product-local passwords and sessions do not become Veltro credentials. Ask users to enroll new passkeys on the new origin; WebAuthn credentials are bound to the previous relying-party host.

Cut over in a maintenance window

1. Fence writes and sign-ins on the source. Wait for in-flight work and product queues to settle, then take a fresh database dump and copies of applicable volumes and OpenSearch data. Verify them before touching the destination. Avoid copying live Redis files while workers are writing.
2. Restore each product into its own empty destination database and volumes with its documented product restore procedure. Check migrations and ownership before starting application containers. Leave the veltro_identity database and the Veltro identity data untouched. Restore Sigmatic indices and any queued work with their own verified procedures; if they cannot be moved safely, drain or account for the work before cutover.
3. Start core plus the selected products. Use veltro status and the product-specific health checks, then verify sign-in and product grants with both an allowed and a denied user. Check product records, attachments, encrypted integrations, Sigmatic indices and pending jobs against the pre-cutover inventory.
4. Move the public endpoint to the Veltro origin. Product browser routes are /vectorflow, /sigmatic/ and /warden/. Update SSO callbacks to Veltro identity’s callback URLs, not a product’s old login callback. For agents pointed at the plain VectorFlow server’s :3000 root, change VF_URL to <origin>/vectorflow for the suite image. Check agent enrollment and generated push URLs on a test agent before rolling this out fleet-wide. Repoint Sigmatic shippers and VectorFlow pipeline sinks to the suite’s /api/logs/… endpoint. Retain bearer secrets only where that machine endpoint still uses them; raw Sigmatic :8001 must stay private.

If old machine hostnames must stay temporarily, proxy agent and ingest paths instead of redirecting them across hosts. Some clients drop Authorization on a cross-host redirect. Retire the bridge only after its access log shows no remaining machine traffic.

Rollback and removing a product

Keep the source read-only during verification. Before new writes, rollback can switch traffic to the untouched source after stopping the new stack. Once users, agents or shippers write to Veltro, switching back loses or forks those writes unless you reconcile them; restoring an old snapshot is not a safe automatic rollback. Record the last accepted write and use a reviewed repair-forward plan if reconciliation is needed.

Removing a product from VELTRO_PRODUCTS stops its services and hides it from the launcher; it does not export data, revoke grants, remove volumes or turn it back into a product-only install. Back it up first, keep its secrets and data, and treat a return to an older product image as a schema downgrade that may be impossible. After switching away from an old standalone Compose stack, orphaned veltro-vectorflow-standalone, chad-frontend or warden-frontend containers may remain; inspect them and use Compose --remove-orphans only after verifying the replacement and backups. Never use volume removal as orphan cleanup.