Deploy a container application with Orcra Run

orun follows a pull-based model: you declare what you want in a YAML manifest, commit it to your manifest Git repository, and every node tracking that branch reconciles the change within seconds. There is no imperative deploy command — pushing a commit is the deployment.

Before you start

Make sure you have:

A bootstrapped node tracking your manifest repository (see Bootstrap a server as an orun node over SSH)
A manifest Git repository with at least one branch the node is configured to track

Create the deployment manifest

Create the file deployments/hello-world.yaml in your manifest repository:

apiVersion: run.orcra.dev/v0alpha
kind: Deployment
metadata:
  name: hello-world
spec:
  image: traefik/whoami
  ports:
    - containerPort: 80
      port: 8080
  health:
    readiness:
      http: localhost:80/health
    liveness:
      http: localhost:80/health
  env:
    LOG_FORMAT: json

Key fields:

Field	Description
`spec.image`	Container image to pull and run
`spec.ports[].containerPort`	Port the container exposes internally
`spec.ports[].port`	Host port to bind on the node
`spec.health.readiness.http`	HTTP endpoint orun polls for readiness
`spec.health.liveness.http`	HTTP endpoint orun polls for liveness
`spec.env`	Environment variables injected into the container

Commit and push to the tracked branch

git add deployments/hello-world.yaml
git commit -m "Add hello-world deployment"
git push

Push to the branch your node is configured to track (default: main). Pushing to a different branch has no effect on nodes that do not track it.

Wait for the node to poll and apply

The node polls the manifest repository on the interval configured during bootstrap (default: 5s). Within a few seconds of your push, orun fetches the new manifest and starts the container.

If the image pull fails — for example due to a network error or a missing registry credential — orun logs the error and retries automatically on the next reconcile cycle.

Verify the container is running

From your local machine, curl the node on the host port you configured:

curl http://<node-ip>:8080

The traefik/whoami image responds with the request headers and container metadata, confirming the deployment is live.

Check the deployment status via the status API

orun exposes a lightweight HTTP status API on port 9100 (localhost on the node). Query it over SSH or an existing tunnel:

curl -X POST http://<node-ip>:9100/status

The response is a NodeReport JSON object containing the state of every deployment the node manages, including each deployment’s lifecycle state (pending, running, stopped, or errored) and any error details.

# Simple liveness check
curl -X POST http://<node-ip>:9100/healthz
# → {"status":"ok"}

The poll interval defaults to 5s and is set per-node in the node manifest via the pollInterval field (e.g., pollInterval: 30s). Shorter intervals mean faster convergence; longer intervals reduce Git API load.

Enable HTTPS ingress

Expose this deployment on a custom domain with automatic TLS via Caddy.

Build images locally

Build container images directly on the node from source instead of pulling from a registry.

Get Started

Core Concepts

Configuration

Guides

Reference

Deploy a container application with Orcra Run

Before you start

Enable HTTPS ingress

Build images locally

​Before you start

Enable HTTPS ingress

Build images locally

Before you start