Local Development Setup
Run the complete Orcher stack locally on your machine for development and testing. With the Orcher CLI and Docker, you can have a full orchestration environment running in minutes.
Choose Your SDK
Prerequisites: • Rust 1.70 or later • Docker Desktop (or compatible container runtime) • PostgreSQL 14+ (optional, Docker setup includes it)
1. Install the Orcher CLI
The Orcher CLI provides commands to manage your local development environment, deploy workflows, and interact with the orchestrator.
Install via Cargo:
1cargo install orcher-cliVerify installation:
1orcher --version2. Install Docker
Orcher uses Docker containers for local development. This gives you an isolated, reproducible environment with all dependencies included.
Follow the official guide to install Docker Desktop:
- Download Docker Desktop for Mac
- Install and start Docker Desktop
- Verify Docker is running:
1docker --versionRecommended Settings: • Enable "Use containerd for pulling and storing images" • Allocate at least 4GB of memory • Enable "Use Virtualization Framework"
Alternative Container Runtimes:
You can use Docker-compatible alternatives: • Rancher Desktop (macOS, Windows, Linux) • Podman (macOS, Windows, Linux) • OrbStack (macOS) • colima (macOS)
3. Start Orcher Server
Start the Orcher orchestrator and all required services using Docker:
1orcher server startOr use Docker directly:
1docker run --name orcher_dev --rm \2 -p 8080:8080 -p 9090:9090 -p 8081:8081 \3 --add-host=host.docker.internal:host-gateway \4 orcherapp/orcher:latestWhat Gets Started:
• Orchestrator Server (port 8080) - Main workflow orchestration engine • gRPC Server (port 9090) - For worker communication • Admin UI (port 8081) - Web-based management interface • PostgreSQL - Workflow journal and state storage
The first run takes longer as Docker downloads the required images (~500MB).
Expected output:
1Orcher Server started successfully23 Orchestrator API: http://localhost:80804 gRPC Server: http://localhost:90905 Admin UI: http://localhost:80816 Database: postgresql://postgres:postgres@localhost:5432/orcher_dev78Ready to accept workflows4. Access Local Services
Once Orcher is running, you can access these services:
1# Default URL:2http://localhost:8081The Admin UI provides a graphical interface for:
• Monitoring workflows - View running, completed, and failed workflows • Workflow playground - Test workflows with custom inputs • Execution history - Inspect journal entries and task executions • Deployment management - Register and manage workers • Metrics dashboard - System health and performance metrics
5. Initialize a Workflow Project
Create a new workflow project in your chosen SDK:
Create a new project:
1orcher new my-workflow2cd my-workflowOr run one of the Rust SDK's examples:
1git clone https://github.com/orcher-io/sdk-rust2cd sdk-rust3cargo run -p orcher-example-durable-execution -- --e2eProject Structure:
1my-workflow/2├── src/3│ ├── main.rs # Worker entry point4│ ├── workflows/ # Workflow definitions5│ │ └── payment.rs6│ └── tasks/ # Task implementations7│ ├── charge_card.rs8│ └── send_email.rs9├── orcher.toml # Configuration10└── Cargo.tomlConfigure the orchestrator URL:
1# orcher.toml2[orchestrator]3url = "http://localhost:9090"45[worker]6port = 90807concurrency = 106. Run Your Worker
Start your worker locally:
1cargo runExpected output:
1Orcher Worker started2 Orchestrator: http://localhost:90903 Worker Port: 90804 Workflows: payment_workflow, order_fulfillment5 Tasks: charge_card, send_email, reserve_inventory6 7Connected to Orcher OrchestratorHot Reload During Development:
Use cargo-watch for automatic recompilation:
1cargo install cargo-watch2cargo watch -x run7. Register Your Worker
Tell Orcher about your worker so it can discover workflows and tasks:
Via Admin UI:
- Open http://localhost:8081
- Navigate to "Deployments"
- Click "Register New Worker"
- Enter endpoint:
http://localhost:9080 - Click "Register"
Via CLI:
1orcher deployments register http://localhost:9080Via curl:
1curl -X POST http://localhost:8080/api/deployments \2 -H "Content-Type: application/json" \3 -d '{"endpoint": "http://localhost:9080"}'Expected output:
1WORKFLOWS THAT WILL BE ADDED:2• payment_workflow (v1.0.0)3• order_fulfillment (v2.1.0)45Are you sure you want to apply those changes? · yes67DEPLOYMENT REGISTERED:8WORKFLOW REV9payment_workflow 110order_fulfillment 2If your worker runs in Docker, register http://host.docker.internal:9080 instead of http://localhost:9080.
8. Test Your Workflows
Now you can execute workflows through the Admin UI, CLI, or API.
Via Admin UI Playground:
- Open http://localhost:8081
- Select your workflow
- Click "Playground"
- Enter test input JSON
- Click "Run"
Via CLI:
1orcher workflow run payment_workflow \2 --input '{"amount": 99.99, "customer": "alice@example.com"}'Via curl:
1curl -X POST http://localhost:8080/api/workflows/start \2 -H "Content-Type: application/json" \3 -d '{4 "workflow": "payment_workflow",5 "input": {6 "amount": 99.99,7 "customer": "alice@example.com"8 }9 }'Development Workflow
Watch Logs
Orchestrator logs:
1docker logs -f orcher_devWorker logs:
Your worker logs appear in the terminal where you ran cargo run.
View Execution History
1orcher workflow list2orcher workflow get <workflow_id>3orcher workflow history <workflow_id>Reset Database
To start fresh:
1orcher server stop2docker volume rm orcher_postgres_data3orcher server startStop Services
Stop the orchestrator:
1orcher server stopOr:
1docker stop orcher_devStop your worker:
Press Ctrl+C in the terminal where it's running.
Environment Variables
Configure your local setup with environment variables:
1# Orchestrator connection2export ORCHER_ORCHESTRATOR_URL="http://localhost:9090"34# Database5export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/orcher_dev"67# Worker configuration8export ORCHER_WORKER_PORT=90809export ORCHER_WORKER_CONCURRENCY=101011# Logging12export RUST_LOG=info13export ORCHER_LOG_FORMAT=jsonTroubleshooting
Port Already in Use
If ports 8080, 8081, or 9090 are already in use:
1# Check what's using the port2lsof -i :808034# Use custom ports5docker run --name orcher_dev --rm \6 -p 8888:8080 -p 9999:9090 -p 8889:8081 \7 orcherapp/orcher:latestUpdate your worker configuration to match:
1[orchestrator]2url = "http://localhost:9999"Docker Connection Issues
If your worker can't connect to the orchestrator:
On macOS/Linux:
1# Use host.docker.internal instead of localhost2export ORCHER_ORCHESTRATOR_URL="http://host.docker.internal:9090"On Linux without Docker Desktop:
1# Add --network=host to docker run2docker run --name orcher_dev --rm --network=host \3 orcherapp/orcher:latestDatabase Migration Issues
If you see database errors:
1# Run migrations manually2orcher migrate34# Or reset the database5orcher server stop6docker volume rm orcher_postgres_data7orcher server startNext Steps
Write Your First Workflow
Testing Workflows
CLI Reference
Learn More
• Configuration Reference - Advanced configuration options • Production Deployment - Deploy Orcher to production environments