Skip to main content
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)
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
2

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

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:
  1. Connects to the node over SSH using the configured key
  2. Detects or installs Docker
  3. Copies the orun binary to the node
  4. Creates and enables a systemd service
  5. 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
4

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

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

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