Production Deployment

Standalone mode is optimized for development and testing only. Production deployments must use the remote mode backed by a highly available Temporal cluster.

Deployment Checklist

Managed Temporal
Use Temporal Cloud or a self-managed Temporal cluster with multi-node frontend, history, matching, and worker services. Verify TLS and authentication.
Durable Datastores
Provision managed PostgreSQL for Compozy metadata and Redis for caching, rate limiting, and configuration layers.
Secrets & Config
Load secrets from your platform (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) and mount compozy.yaml with read-only permissions.
Observability
Enable structured logging, metrics export, and distributed tracing in both Compozy and Temporal. Ensure alerts cover queue backlogs and workflow failures.

Database Selection

Production deployments must use PostgreSQL. SQLite is limited to 5-10 concurrent workflows and should remain in development or edge environments only.

Production database configuration

database:
  driver: postgres
  conn_string: postgres://compozy:${DB_PASSWORD}@postgres.prod.internal:5432/compozy?sslmode=verify-full

knowledge:
  vector_dbs:
    - id: main
      provider: pgvector
      dimension: 1536

Enable the pgvector extension to keep embeddings in the same PostgreSQL cluster.
Grant least-privilege credentials: schema migrations need CREATE, runtime requires CRUD permissions.
Capture automated backups (RDS snapshots, PITR) before major releases.

For staging environments that mimic production, follow the same PostgreSQL configuration and capacity planning guidance. See the Database Overview for the full decision matrix.

Recommended Configuration

Configure remote mode explicitly in your project configuration. Compozy will refuse to start if temporal.mode is missing in production builds.

compozy.yaml

server:
  environment: production

temporal:
  mode: remote
  host_port: temporal.my-company.internal:7233
  namespace: compozy-prod
  task_queue: compozy-tasks

runtime:
  environment: production

Start with hardened settings

COMPOZY_CONFIG_FILE=./compozy.yaml \
  compozy start \
    --format json \
    --temporal-mode=remote \
    --temporal-host=temporal.my-company.internal:7233

Validate the remote Temporal cluster before switching traffic. Run compozy diagnostics temporal (if enabled) or temporal workflow list to confirm connectivity and namespace health.

Best Practices

Concern	Guidance
High availability	Deploy Temporal with at least 3 history and 2 frontend instances. Use load balancers with health checks on port 7233.
Security	Enable mTLS between Compozy and Temporal. Lock down the Temporal Web UI to trusted networks only.
Namespaces	Use dedicated namespaces per environment (dev, staging, prod) to isolate retention policies and rate limits.
Task queues	Partition workloads using multiple task queues when different latency or concurrency guarantees are required.
Disaster recovery	Configure Temporal replication or backups. Test failover playbooks quarterly.

Choosing a Mode

Criterion	Choose Distributed	Choose Standalone
Durability / HA	Yes	No
Team size & shared env	Team / shared	Solo dev / CI
Operational complexity	Higher	Lower

Refer to Mode Configuration for inheritance and overrides.

Migration Tips

Plan a low-traffic maintenance window.
Update temporal.mode to remote in configuration management.
Point workers to the production Temporal cluster.
Restart Compozy servers to pick up the new configuration.
Monitor workflow metrics and queues closely for the first 30 minutes.