Migrate from v1 to v2
Step-by-step instructions for planning and executing your EQUOS9 v2 cutover.
1. Verify compatibility
| Requirement | Notes |
|---|---|
| Node.js 20 LTS | Required for the new multi-runtime deploy target. |
| PostgreSQL 15 | Use logical replication to sync with existing clusters. |
| Redis 7.2 | Needed for background job tracing. |
Identify tenants using legacy features (for example, regional RBAC rules) and schedule time to review them after the upgrade.
2. Shadow deploy
- Clone your current workspace:
equos workspace clone --from <v1-id> --to <shadow-id>. - Enable the shadow feature flag in the EQUOS9 UI.
- Deploy the clone to v2 infrastructure.
This creates a read-only copy that receives production traffic but does not emit customer-facing changes.
3. Execute the cutover
- Pause scheduled jobs in v1.
- Enable write traffic on the shadow deployment.
- Point DNS to the v2 ingress endpoint.
- Unlock jobs and monitor health dashboards.
Most teams finish the cutover in under 30 minutes. If you encounter blockers, roll back by pointing DNS to the previous endpoint and restoring the job scheduler.
Follow-up
- Complete the post-migration checklist in the admin UI.
- Invite your team to the new versioned docs by sharing the
/docs/v2/URL. - Delete the frozen v1 workspace once you confirm billing data is reconciled.