Skip to main content
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:
1

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:
FieldDescription
spec.imageContainer image to pull and run
spec.ports[].containerPortPort the container exposes internally
spec.ports[].portHost port to bind on the node
spec.health.readiness.httpHTTP endpoint orun polls for readiness
spec.health.liveness.httpHTTP endpoint orun polls for liveness
spec.envEnvironment variables injected into the container
2

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.
3

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.
4

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.
5

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.