Skip to main content
orun ships an embedded Caddy server that handles HTTP/HTTPS routing and TLS certificate provisioning automatically. You do not need to install or configure Nginx, Traefik, or any other reverse proxy — creating a Service manifest is all it takes to put a deployment behind a domain with valid SSL.

​
Prerequisites

Point your DNS record at the node before setting ssl: true. Caddy provisions certificates via Let’s Encrypt HTTP-01 challenges on port 80. If DNS does not resolve to the node at that moment, certificate provisioning fails and Caddy retries with backoff.
1

Create the Service manifest

Create the file services/hello-world.yaml in your manifest repository:
apiVersion: run.orcra.dev/v0alpha
kind: Service
metadata:
  name: hello-world
spec:
  deployment: hello-world
  ingress:
    domain:
      default: hello-world.example.com
    ssl: true
Key fields:
FieldRequiredDefaultDescription
spec.deploymentYes—Name of the Deployment to route traffic to
spec.ingress.domain.defaultYes—Primary domain for this service
spec.ingress.sslNofalseEnable automatic TLS via Caddy and Let’s Encrypt
2

Commit and push

git add services/hello-world.yaml
git commit -m "Add hello-world service with SSL"
git push
3

Wait for the node to pick up the change

Within one poll interval (default 5s), the node reads the new Service manifest and reconfigures Caddy. Caddy begins the Let’s Encrypt ACME flow immediately, which typically completes within a few seconds when DNS is already propagated.
4

Verify HTTPS is working

Open a browser or run:
curl https://hello-world.example.com
You should receive a valid response with a trusted Let’s Encrypt certificate. Caddy handles certificate renewal automatically before expiry.
5

Use per-environment domains (optional)

If you use Git branches as environments, you can configure a domain template that includes the branch name:
spec:
  deployment: hello-world
  ingress:
    domain:
      default: hello-world.example.com
      environment: hello-world.$ENV.example.com
    ssl: true
The $ENV placeholder is replaced at runtime with the name of the branch the node is tracking. For example, a node on the staging branch serves hello-world.staging.example.com, while a node on main falls back to hello-world.example.com.
The embedded Caddy HTTP and HTTPS ports default to 80 and 443. You can override them with the --caddy-http-port and --caddy-https-port flags passed to orun start. This is useful when testing locally or when another process holds the standard ports.

Deploy your first app

Create a Deployment manifest that orun pulls and runs automatically.

Monitor containers and view logs

Inspect orun agent logs and query the status API for deployment health.