Get started with Orcra Run

This guide walks you through installing orun, creating a manifest repository, provisioning a remote server as an orun node, and deploying your first container. By the end you will have a live workload reconciled automatically from Git.

Prerequisites

A Linux VPS or dedicated server you can reach over SSH
Git installed on your local machine
The orun binary installed locally (see Step 1)

Install the orun binary

Download the orun binary from the GitHub releases page and place it somewhere on your PATH.

# After downloading, make the binary executable and move it to your PATH
chmod +x orun
mv orun /usr/local/bin/orun

Verify the installation:

orun --help

Create a manifest repository

orun bootstrap must be run from the root of your manifest repository. Create one now.

mkdir my-infra && cd my-infra
git init
git remote add origin git@github.com:your-org/my-infra.git

The repository layout orun expects:

deployments/   # Deployment manifests
nodes/         # Node manifests (written by orun bootstrap)
services/      # Service manifests

Push the repository to a remote before bootstrapping. The node needs a URL it can clone from — orun uses the origin remote of your manifest repository as the pull source.

Bootstrap your first node

Run orun bootstrap from the manifest repository root. With no arguments, it starts an interactive prompt:

orun bootstrap

orun asks a series of questions:

No manifest provided. Please answer the following questions to configure the node.

  Node name (e.g. web-01): web-01
  Host (IP or hostname): 203.0.113.10
  SSH user [root]:
  SSH private key path [~/.ssh/id_ed25519]:
  Manifest git repository URL (e.g. git@github.com:org/manifests.git): git@github.com:your-org/my-infra.git
  Git branch [main]:
  Poll interval (e.g. 5s, 1m) [5s]:
  Data directory on the node [/opt/orun/]:

  → Node manifest written to nodes/web-01.yaml

After you answer, orun writes nodes/web-01.yaml and proceeds to provision the server. During bootstrap it:

Connects to the node over SSH using the configured key
Detects or installs Docker
Copies the orun binary to the node
Creates and enables a systemd service
Verifies the service is running

Once bootstrap completes, SSH access is no longer required. The node operates autonomously.

If you already have a node manifest from a previous bootstrap, pass it directly to skip the interactive prompt:

orun bootstrap nodes/web-01.yaml

The node clones your manifest repository using the origin remote URL you provided. Make sure the node has read access — for a private GitHub repository, add a deploy key to the repo and place the corresponding private key on the node at the path orun start expects.

Commit and push the generated node manifest:

git add nodes/web-01.yaml
git commit -m "Add web-01 node manifest"
git push

Deploy your first container

Create a Deployment manifest in deployments/hello-world.yaml:

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

This runs traefik/whoami, binds the container’s port 80 to host port 8080, and configures HTTP readiness and liveness checks.

Commit and push

Commit the manifest and push to the branch your node is tracking (main by default):

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

The node polls for changes every 5 seconds. Within a few seconds of your push, it pulls the new commit, starts the container, and begins health-checking it.

(Optional) Expose the container with a Service

To route HTTP/HTTPS traffic to your Deployment through the built-in Caddy ingress, create services/hello-world.yaml:

apiVersion: run.orcra.dev/v0alpha
kind: Service
metadata:
  name: hello-world
spec:
  deployment: hello-world
  ingress:
    domain:
      default: hello-world.example.com
    ssl: true

Point hello-world.example.com at your node’s IP address, then commit and push. Caddy provisions a TLS certificate automatically via ACME on the first request.

git add services/hello-world.yaml
git commit -m "Expose hello-world via ingress"
git push

Set ssl: true only after your DNS record is live and propagated. Caddy performs an ACME HTTP-01 challenge on port 80 to provision the certificate.

What’s next

How it works

Understand the pull-based reconciliation loop in depth.

Node configuration

All Node manifest fields: SSH, Git, poll interval, data directory.

Deployment configuration

Ports, volumes, environment variables, and health checks.

SSL and ingress

Configure custom domains and automatic TLS for your services.

Get Started

Core Concepts

Configuration

Guides

Reference

Get started with Orcra Run

Prerequisites

What’s next

How it works

Node configuration

Deployment configuration

SSL and ingress

​Prerequisites

​What’s next

How it works

Node configuration

Deployment configuration

SSL and ingress

Prerequisites

What’s next