Quickstart#

Set up a cluster and deploy a web service. Complete the installation requirements before you begin.

Controller#

Copy a trusted Linux amd64 orch executable to the controller host and run:

sudo ./orch init

Allow TCP 9443 from trusted workers and operators. On your workstation, add a target that reaches the controller over SSH as root:

orch target add production ssh://root@10.0.0.10

Worker#

Create a join token on your workstation (or as root on the controller):

orch join-token worker-1

Copy the orch executable to the worker and run the printed command there:

sudo ./orch join orch1.eyJlIjoiaHR0cHM6Ly8xMC4wLjAuMTA6OTQ0MyIs...

Allow UDP 51820 between workers. For public ingress, route DNS to an ingress-enabled node and allow TCP 80 and 443.

Application#

Create orch.pkl:

amends "orch:/v1alpha1/Application.pkl"

name = "hello"

services {
  ["web"] {
    image = "ghcr.io/acme/hello:1.2.3"
    replicas = 1
    resources {
      cpu = "250m"
      memory = "128Mi"
    }
    http = new Http {
      port = 8080
      domains { "hello.example.com" }
      healthPath = "/healthz"
    }
  }
}

deploy {
  maxSurge = 1
  maxUnavailable = 0
  autoRollback = true
}

The image must listen on port 8080 and return success from /healthz.

Deployment#

orch validate
orch plan
orch deploy --wait --target production
orch app status hello --target production

orch resolves image tags to immutable digests, waits for readiness, and records the deployment result. A failed update automatically returns traffic to the last healthy revision when autoRollback is enabled.

Continue with application configuration, learn the runtime and rollout contract, or review deployment history and manual rollback.