Skip to main content
In orun, the Git repository is the control plane. There is no dashboard, no API server, and no database storing desired state — everything lives in YAML files committed to Git. When you want to change what runs on a node, you change a file and push. The node picks it up on the next poll cycle.

​
Directory layout

orun expects three top-level directories in your manifest repository. Each directory holds one kind of resource: 
nodes/
  web-01.yaml
deployments/
  helloworld.yaml
services/
  helloworld.yaml
Node manifests describe a single host: its address, the Git repository and branch it should track, and runtime parameters such as poll interval and data directory. orun reads these files during orun bootstrap to provision new hosts. Committing node manifests to the repository means adding a new node is as simple as running orun bootstrap nodes/<name>.yaml — no manual configuration on the host.
Deployment manifests describe a containerized workload: the image to run, port bindings, health check endpoints, volume mounts, and environment variables. Each file corresponds to one container managed by orun on every node that tracks this repository.
Service manifests wire a Deployment to the built-in Caddy ingress: they specify which Deployment to expose, the public domain name, and whether to enable automatic SSL/TLS. The ingress.domain.environment field uses $ENV as a placeholder that orun replaces with the environment suffix at runtime.

​
Resource kinds

All resources share the same apiVersion. The kind field tells orun how to interpret the file. 
apiVersion: run.orcra.dev/v0alpha
kind: Node | Deployment | Service
metadata:
  name: <resource-name>
spec:
  ...

​
Node

apiVersion: run.orcra.dev/v0alpha
kind: Node
metadata:
  name: web-01
spec:
  host: 203.0.113.10
  user: root
  sshKeyPath: ~/.ssh/id_ed25519
  gitRepo: git@github.com:org/manifests.git
  gitBranch: main
  pollInterval: 5s
  dataDir: /opt/orun/
FieldRequiredDefaultDescription
hostYes—SSH host or IP address of the target node
userNorootSSH user for the bootstrap connection
sshKeyPathNo~/.ssh/id_ed25519Path to SSH private key on the machine running orun bootstrap
gitRepoYes—URL of the manifest Git repository
gitBranchNomainBranch the node tracks after bootstrap
pollIntervalNo5sHow often the node polls for manifest changes
dataDirNo/opt/orun/Local state directory on the node

​
Deployment

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
  volumes:
    - hostPath: /var/storage/db
      containerPath: /db
  env:
    LOG_FORMAT: json
FieldRequiredDefaultDescription
imageYes*—Container image to run. Mutually exclusive with build.
build.contextYes*—Build context path. Required when using build instead of image.
build.dockerfileNo—Path to Dockerfile within the build context
build.buildModeNobuild-oncebuild-once or watch
ports[].containerPortYes—Port exposed by the container (1–65535)
ports[].portYes—Host port to bind to (1–65535)
health.readiness.httpNo—HTTP endpoint polled for readiness
health.liveness.httpNo—HTTP endpoint polled for liveness
volumes[].hostPathNo—Path on the host to mount
volumes[].containerPathNo—Path inside the container
envNo—Environment variables passed to the container
*Exactly one of image or build is required.

​
Service

apiVersion: run.orcra.dev/v0alpha
kind: Service
metadata:
  name: hello-world
spec:
  deployment: hello-world
  ingress:
    domain:
      default: hello-world.orcra.dev
      environment: hello-world.$ENV.orcra.dev
    ssl: true
FieldRequiredDefaultDescription
deploymentYes—Name of the Deployment to expose
ingress.domain.defaultYes—Domain used when no environment suffix applies
ingress.domain.environmentNo—Domain template for environment-specific routing; $ENV is replaced with the environment suffix
ingress.sslNofalseEnable automatic SSL/TLS via Caddy

​
Git authentication

The node fetches from the origin remote of the manifest repository. Ensure the node has read access before running orun bootstrap.

​
Poll interval and change propagation

The node polls the origin remote every pollInterval seconds (default: 5s). After you push a commit, the node picks it up within one poll cycle. Reduce pollInterval for faster convergence, or increase it to reduce Git API load on shared hosts. 
spec:
  pollInterval: 10s   # node checks for changes every 10 seconds
Commit your Node manifests to the repository. When you need to provision a new node, run orun bootstrap nodes/<name>.yaml against the committed file. You get a full audit trail of node configuration changes in Git history at no extra cost.