Migrate: Standalone → Distributed

This guide helps you move from standalone (embedded services) to distributed/remote mode.

When to Migrate

• Team adoption grows and you need shared environments
• You require durability, HA, and predictable performance
• You need production‑grade monitoring, backups, and access controls

Prerequisites

• A managed or self‑hosted Temporal cluster reachable by Compozy
• A managed Redis cluster (or equivalent) for cache and rate limiting
• Updated secrets management for production endpoints

Step‑by‑Step

1. Provision infrastructure

# Example placeholders
export TEMPORAL_HOST_PORT=temporal.prod.internal:7233
export REDIS_ADDR=redis.prod.internal:6379

2. Update configuration

mode: distributed

temporal:
  mode: remote
  host_port: ${TEMPORAL_HOST_PORT}
  namespace: compozy-prod
  task_queue: compozy-tasks

redis:
  mode: distributed
  distributed:
    addr: ${REDIS_ADDR}
    password: ${REDIS_PASSWORD}
    tls:
      enabled: true

3. Restart services

compozy start --temporal-mode=remote --format json

4. Validate

• temporal workflow list --namespace compozy-prod
• Health checks on Compozy HTTP and Temporal connectivity

5. Clean up standalone artifacts

• Remove temporal.standalone.* overrides if not needed
• Remove/archive local snapshot directories

Rollback

If you need to roll back, switch mode back to standalone, re‑enable temporal.standalone, and restart. Confirm via the Temporal UI locally.

Troubleshooting

• TLS handshake errors: verify certificates and CA chains
• Increased latency: check network path, namespace rate limits, and task queue backlogs
• Auth failures to Redis: verify credentials and required ACLs

References