Local Development

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:

1
cargo install orcher-cli

Verify installation:

1
orcher --version

2. 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:

  1. Download Docker Desktop for Mac
  2. Install and start Docker Desktop
  3. Verify Docker is running:
1
docker --version

Recommended Settings: • Enable "Use containerd for pulling and storing images" • Allocate at least 4GB of memory • Enable "Use Virtualization Framework"


3. Start Orcher Server

Start the Orcher orchestrator and all required services using Docker:

1
orcher server start

Or use Docker directly:

1
docker 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:latest

What 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

Expected output:

1
Orcher Server started successfully
2
3
Orchestrator API: http://localhost:8080
4
gRPC Server: http://localhost:9090
5
Admin UI: http://localhost:8081
6
Database: postgresql://postgres:postgres@localhost:5432/orcher_dev
7
8
Ready to accept workflows

4. Access Local Services

Once Orcher is running, you can access these services:

1
# Default URL:
2
http://localhost:8081

The 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:

1
orcher new my-workflow
2
cd my-workflow

Or run one of the Rust SDK's examples:

1
git clone https://github.com/orcher-io/sdk-rust
2
cd sdk-rust
3
cargo run -p orcher-example-durable-execution -- --e2e

Project Structure:

1
my-workflow/
2
├── src/
3
│ ├── main.rs # Worker entry point
4
│ ├── workflows/ # Workflow definitions
5
│ │ └── payment.rs
6
│ └── tasks/ # Task implementations
7
│ ├── charge_card.rs
8
│ └── send_email.rs
9
├── orcher.toml # Configuration
10
└── Cargo.toml

Configure the orchestrator URL:

1
# orcher.toml
2
[orchestrator]
3
url = "http://localhost:9090"
4
5
[worker]
6
port = 9080
7
concurrency = 10

6. Run Your Worker

Start your worker locally:

1
cargo run

Expected output:

1
Orcher Worker started
2
Orchestrator: http://localhost:9090
3
Worker Port: 9080
4
Workflows: payment_workflow, order_fulfillment
5
Tasks: charge_card, send_email, reserve_inventory
6
7
Connected to Orcher Orchestrator

Hot Reload During Development:

Use cargo-watch for automatic recompilation:

1
cargo install cargo-watch
2
cargo watch -x run

7. Register Your Worker

Tell Orcher about your worker so it can discover workflows and tasks:

Via Admin UI:

  1. Open http://localhost:8081
  2. Navigate to "Deployments"
  3. Click "Register New Worker"
  4. Enter endpoint: http://localhost:9080
  5. Click "Register"

Via CLI:

1
orcher deployments register http://localhost:9080

Via curl:

1
curl -X POST http://localhost:8080/api/deployments \
2
-H "Content-Type: application/json" \
3
-d '{"endpoint": "http://localhost:9080"}'

Expected output:

1
WORKFLOWS THAT WILL BE ADDED:
2
• payment_workflow (v1.0.0)
3
• order_fulfillment (v2.1.0)
4
5
Are you sure you want to apply those changes? · yes
6
7
DEPLOYMENT REGISTERED:
8
WORKFLOW REV
9
payment_workflow 1
10
order_fulfillment 2

8. Test Your Workflows

Now you can execute workflows through the Admin UI, CLI, or API.

Via Admin UI Playground:

  1. Open http://localhost:8081
  2. Select your workflow
  3. Click "Playground"
  4. Enter test input JSON
  5. Click "Run"

Via CLI:

1
orcher workflow run payment_workflow \
2
--input '{"amount": 99.99, "customer": "alice@example.com"}'

Via curl:

1
curl -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:

1
docker logs -f orcher_dev

Worker logs:

Your worker logs appear in the terminal where you ran cargo run.

View Execution History

1
orcher workflow list
2
orcher workflow get <workflow_id>
3
orcher workflow history <workflow_id>

Reset Database

To start fresh:

1
orcher server stop
2
docker volume rm orcher_postgres_data
3
orcher server start

Stop Services

Stop the orchestrator:

1
orcher server stop

Or:

1
docker stop orcher_dev

Stop your worker:

Press Ctrl+C in the terminal where it's running.


Environment Variables

Configure your local setup with environment variables:

1
# Orchestrator connection
2
export ORCHER_ORCHESTRATOR_URL="http://localhost:9090"
3
4
# Database
5
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/orcher_dev"
6
7
# Worker configuration
8
export ORCHER_WORKER_PORT=9080
9
export ORCHER_WORKER_CONCURRENCY=10
10
11
# Logging
12
export RUST_LOG=info
13
export ORCHER_LOG_FORMAT=json

Troubleshooting

Port Already in Use

If ports 8080, 8081, or 9090 are already in use:

1
# Check what's using the port
2
lsof -i :8080
3
4
# Use custom ports
5
docker run --name orcher_dev --rm \
6
-p 8888:8080 -p 9999:9090 -p 8889:8081 \
7
orcherapp/orcher:latest

Update your worker configuration to match:

1
[orchestrator]
2
url = "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 localhost
2
export ORCHER_ORCHESTRATOR_URL="http://host.docker.internal:9090"

On Linux without Docker Desktop:

1
# Add --network=host to docker run
2
docker run --name orcher_dev --rm --network=host \
3
orcherapp/orcher:latest

Database Migration Issues

If you see database errors:

1
# Run migrations manually
2
orcher migrate
3
4
# Or reset the database
5
orcher server stop
6
docker volume rm orcher_postgres_data
7
orcher server start

Next Steps


Learn More

• Configuration Reference - Advanced configuration options • Production Deployment - Deploy Orcher to production environments