Skip to main content
Instead of pushing images to a container registry and pulling them back down, orun can build container images directly on the node from local source code. This is useful for development workflows where you want rapid iteration, or for airgapped environments where registry access is not available. You configure the build by replacing the image field in your Deployment manifest with a build spec.

​
How it works

Source code lives in a directory on the node called codeDir (default: /var/lib/orun/code). Each subdirectory within codeDir can be a separate build context. You reference the subdirectory name in your Deployment’s build.context field. orun supports two build modes:
  • build-once (default) — builds the image when the Deployment is first applied or when the manifest changes. Use this for production or CI-style workflows.
  • watch — monitors the source directory for file-system changes and rebuilds automatically with a 500 ms debounce. Use this during local development for a fast feedback loop.
image and build are mutually exclusive. A Deployment manifest must specify one or the other, not both.
1

Place your source code on the node

Copy or clone your application source into a subdirectory of codeDir on the node. Using the default codeDir:
# From your local machine
scp -r ./my-app root@<node-ip>:/var/lib/orun/code/my-app/
Or SSH into the node and clone the repository directly:
ssh root@<node-ip>
git clone git@github.com:org/my-app.git /var/lib/orun/code/my-app
Ensure a Dockerfile exists at the root of the context directory (or set build.dockerfile to a custom path).
2

Create a Deployment manifest with build-once mode

Create deployments/my-app.yaml in your manifest repository:
apiVersion: run.orcra.dev/v0alpha
kind: Deployment
metadata:
  name: my-app
spec:
  build:
    context: my-app
    dockerfile: Dockerfile
    buildMode: build-once
  ports:
    - containerPort: 3000
      port: 3000
The build.context value (my-app) is resolved as a subdirectory under codeDir, so orun builds from /var/lib/orun/code/my-app/.
3

Switch to watch mode for active development

Change buildMode to watch and push the updated manifest:
spec:
  build:
    context: my-app
    buildMode: watch
With watch mode active, orun starts a file-system watcher on /var/lib/orun/code/my-app/. Any file change triggers a rebuild after a 500 ms debounce window, then restarts the container with the new image automatically.
Watch mode is well-suited to local development environments. For production deployments, prefer build-once or pull from a container registry using the image field to keep builds deterministic and reproducible.
4

Commit and push the manifest

git add deployments/my-app.yaml
git commit -m "Add my-app deployment with local build"
git push
The node picks up the manifest on the next poll cycle, triggers the image build using the Docker daemon, and starts the container once the build succeeds.

​
Build spec field reference

FieldRequiredDefaultDescription
build.contextYes—Subdirectory name within codeDir to use as the build context
build.dockerfileNoDockerfilePath to the Dockerfile, relative to the build context
build.argsNo—Map of build-time arguments passed to docker build --build-arg
build.buildModeNobuild-onceRebuild behaviour: "build-once" or "watch"
codeDir defaults to /var/lib/orun/code on the node. To use a different path, set the codeDir field in the Node manifest (e.g., codeDir: /data/code) and ensure the orun start process is restarted to pick up the change.

Deploy your first app

Pull an image from a registry and run it with a Deployment manifest.

Monitor containers and view logs

Watch build output and container status via journald and the status API.