Cloud Platforms
Orcher runs on any cloud platform that supports containers and PostgreSQL. The orchestrator is a stateless gRPC/HTTP server — all state lives in PostgreSQL. This means you can run it on managed Kubernetes (EKS, GKE, AKS), container services (ECS, Cloud Run), or plain VMs, connecting to managed PostgreSQL and optionally managed Redis.
- Stateless orchestrator — No local state; scale horizontally behind a load balancer
- Managed databases — Use RDS, Cloud SQL, or Azure Database for PostgreSQL instead of self-managed instances
- Container registry — CI pushes images to GitHub Container Registry (ghcr.io); mirror to ECR, GCR, or ACR for production
- Kubernetes-first — Production manifests in
services/orchestrator/k8s/work on any managed Kubernetes service
Architecture
A cloud deployment consists of three components:
- Orchestrator — Stateless container(s) running the
orchestratorbinary. Exposes gRPC (50051) for SDK workers and HTTP (8080) for health/metrics. - PostgreSQL — Primary data store for workflow state, journal, task executions. Use a managed service with automated backups and failover.
- Redis (optional) — Fast-path dispatch with LPUSH/BRPOP. Workers learn of new work at once instead of at the next poll. Use a managed service or omit entirely — the system falls back to PostgreSQL polling.
SDK workers run wherever your application code runs (ECS tasks, Kubernetes pods, serverless functions, VMs) and connect to the orchestrator's gRPC endpoint.
Container Image
CI Pipeline
The GitHub Actions CI pipeline (.github/workflows/ci.yml) builds and pushes Docker images to GitHub Container Registry on every push to main:
1- name: Login to GitHub Container Registry2 uses: docker/login-action@v33 with:4 registry: ghcr.io5 username: ${{ github.actor }}6 password: ${{ secrets.GITHUB_TOKEN }}78- name: Build and push Docker image9 uses: docker/build-push-action@v510 with:11 context: .12 file: ./services/orchestrator/Dockerfile13 push: true14 tags: ${{ steps.meta.outputs.tags }}Images are tagged by branch, PR number, commit SHA, and latest.
Mirror to Cloud Registry
For production, mirror to your cloud provider's registry:
1# AWS ECR2aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com3docker tag ghcr.io/your-org/orcher:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/orcher:v1.0.04docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/orcher:v1.0.056# GCP Artifact Registry7docker tag ghcr.io/your-org/orcher:latest us-docker.pkg.dev/your-project/orcher/orchestrator:v1.0.08docker push us-docker.pkg.dev/your-project/orcher/orchestrator:v1.0.0910# Azure ACR11az acr login --name yourregistry12docker tag ghcr.io/your-org/orcher:latest yourregistry.azurecr.io/orcher:v1.0.013docker push yourregistry.azurecr.io/orcher:v1.0.0Update the Kustomize image reference to pull from your cloud registry:
1cd services/orchestrator/k8s2kustomize edit set image orcher/orchestrator=123456789.dkr.ecr.us-east-1.amazonaws.com/orcher:v1.0.03kubectl apply -k .Next Steps
- Managed Databases — PostgreSQL, PgBouncer, and Redis configuration
- Cloud Providers — AWS, GCP, and Azure deployment guides
- Operations — High availability, monitoring, and secrets management
- Docker — Docker Compose setup for local development
- Kubernetes — Kubernetes manifests reference
- Configuration — Full configuration reference