Operations

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:

  1. Orchestrator — Stateless container(s) running the orchestrator binary. Exposes gRPC (50051) for SDK workers and HTTP (8080) for health/metrics.
  2. PostgreSQL — Primary data store for workflow state, journal, task executions. Use a managed service with automated backups and failover.
  3. 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 Registry
2
uses: docker/login-action@v3
3
with:
4
registry: ghcr.io
5
username: ${{ github.actor }}
6
password: ${{ secrets.GITHUB_TOKEN }}
7
8
- name: Build and push Docker image
9
uses: docker/build-push-action@v5
10
with:
11
context: .
12
file: ./services/orchestrator/Dockerfile
13
push: true
14
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 ECR
2
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
3
docker tag ghcr.io/your-org/orcher:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/orcher:v1.0.0
4
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/orcher:v1.0.0
5
6
# GCP Artifact Registry
7
docker tag ghcr.io/your-org/orcher:latest us-docker.pkg.dev/your-project/orcher/orchestrator:v1.0.0
8
docker push us-docker.pkg.dev/your-project/orcher/orchestrator:v1.0.0
9
10
# Azure ACR
11
az acr login --name yourregistry
12
docker tag ghcr.io/your-org/orcher:latest yourregistry.azurecr.io/orcher:v1.0.0
13
docker push yourregistry.azurecr.io/orcher:v1.0.0

Update the Kustomize image reference to pull from your cloud registry:

1
cd services/orchestrator/k8s
2
kustomize edit set image orcher/orchestrator=123456789.dkr.ecr.us-east-1.amazonaws.com/orcher:v1.0.0
3
kubectl apply -k .

Next Steps