Skip to main content
A Deployment manifest is a YAML file stored at deployments/<name>.yaml in your manifest repository. It describes a containerized workload that orun runs and reconciles on each node. You can either pull a pre-built image from a container registry or instruct orun to build the image from source code on the node. Every time the node detects a new commit on the tracked branch, it reconciles all Deployment manifests and restarts containers whose configuration has changed.

​
Modes

Deployments support two mutually exclusive modes: image-based and build-based. Set either spec.image or spec.build, never both.
Pull a container image from a registry and run it directly.
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

​
Fields

​
Image

​
image
string
Container image to pull and run, in standard Docker image reference format (e.g. nginx:alpine, ghcr.io/org/app:latest). Mutually exclusive with build. One of image or build is required.

​
Build

​
build
object
Configuration for building the container image from source on the node. Mutually exclusive with image. One of image or build is required.
​
build.context
string
required
Path to the build context directory, relative to codeDir on the node. For example, my-app resolves to <codeDir>/my-app.
​
build.dockerfile
string
Path to the Dockerfile, relative to the build context. Defaults to Dockerfile in the context directory when omitted.
​
build.args
object
Map of build-time arguments passed to Docker as --build-arg flags. Values are plain strings.
build:
  context: my-app
  args:
    NODE_ENV: production
    APP_VERSION: "1.2.3"
​
build.buildMode
string
default:"build-once"
Controls when orun rebuilds the image. Accepted values:
  • build-once — Build the image once when the Deployment is first applied, then reuse it.
  • watch — Rebuild the image whenever orun detects file changes in the build context.
Use buildMode: watch during active development so that pushing source code changes to the node triggers an automatic rebuild and container restart.

​
Ports

​
ports
object[]
List of port bindings that map container ports to host ports on the Docker network.
​
ports[].containerPort
number
required
Port the container listens on. Must be between 1 and 65535.
​
ports[].port
number
required
Host port to bind to. Must be between 1 and 65535. The container is reachable at <host-ip>:<port> from outside the node.

​
Health checks

​
health
object
Configures liveness and readiness probes for the container. Both probes are optional and independent of one another.
​
health.readiness.http
string
HTTP endpoint polled to determine whether the container is ready to serve traffic. Specify as <host>:<port><path>, for example localhost:80/health. orun polls this endpoint after startup.
​
health.liveness.http
string
HTTP endpoint polled continuously to determine whether the container is still healthy. Use the same or a different endpoint from readiness. If the liveness check fails, orun will restart the container.

​
Volumes

​
volumes
object[]
List of bind mounts between host paths and container paths.
​
volumes[].hostPath
string
Absolute path on the node host to mount into the container. The directory must exist on the node before the container starts.
​
volumes[].containerPath
string
Absolute path inside the container where the host directory is mounted.

​
Environment variables

​
env
object
Map of environment variable names to values injected into the container at startup. Values are plain strings. To use secrets, see the secrets documentation.
env:
  LOG_FORMAT: json
  PORT: "8080"
  DATABASE_URL: postgres://localhost/mydb
Environment variable values that match the pattern ENC[AES256_GCM,...] are automatically decrypted by orun at apply time when a valid age key is present on the node. See Encrypting secrets for details.