Skip to content

Latest commit

 

History

History
156 lines (119 loc) · 7.56 KB

README.md

File metadata and controls

156 lines (119 loc) · 7.56 KB

@nexploy/build-runner

Remote build runner for Nexploy. Install it on a spare machine, point it at your Nexploy server, and image builds move off your production host: the runner clones the repository, builds the Docker image and pushes it to your registry, while production only ever does a docker pull.

  • Outbound-only. The runner dials Nexploy over WebSocket. No inbound port, no Docker socket exposed on the network, works behind NAT.
  • Multi-server. One runner process talks to one Nexploy server; run several containers side by side to serve several servers, or several runners against one server for parallelism.
  • Docker-native install. One container, one Docker socket mount.

How it fits in

        ┌────────────────────────┐                        ┌──────────────────────────┐
        │   Nexploy (prod host)  │                        │   Build host (this repo) │
        │                        │   wss:// (outbound)    │                          │
        │  pipeline orchestrator │ ◄────────────────────► │   build-runner container │
        │  runner gateway        │   jobs, logs, results  │   git clone               │
        │                        │                        │   docker build           │
        └───────────┬────────────┘                        │   docker push            │
                    │                                     └────────────┬─────────────┘
                    │ docker pull                                      │ push
                    ▼                                                  ▼
              production containers  ◄───────────────────────────  container registry

The heavy work (git checkout, docker build, layer compression, registry upload) happens on the build host. The production host stays responsive: it only pulls the finished image.


Install

Docker run

docker run -d \
  --name nexploy-build-runner \
  --restart unless-stopped \
  -e NEXPLOY_URL=https://nexploy.example.com \
  -e NEXPLOY_RUNNER_TOKEN=nxr_xxxxxxxxxxxxxxxxxxxxx \
  -e NEXPLOY_RUNNER_NAME=build-runner-1 \
  -e NEXPLOY_RUNNER_CONCURRENCY=2 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v nexploy-runner-workspace:/workspace \
  nexploy/build-runner:latest

Docker Compose

cp .env.example .env   # fill in NEXPLOY_URL and NEXPLOY_RUNNER_TOKEN
docker compose up -d
docker compose logs -f build-runner

The bundled docker-compose.yml mounts the Docker socket, keeps the workspace on a named volume, and binds the health endpoint to 127.0.0.1:9090 only.

Build the image yourself

docker build -t nexploy/build-runner:local .

NEXPLOY_RUNNER_TOKEN is the runner token issued by the Nexploy server. The server side of this protocol — runner registration, the /api/ws/runner gateway and job dispatch — is specified in PROTOCOL.md and is not part of this repository.


Configuration

Variable Default Description
NEXPLOY_URL required Base URL of the Nexploy server, e.g. https://nexploy.example.com. A path prefix is preserved.
NEXPLOY_RUNNER_TOKEN required Runner token issued by Nexploy (min. 16 characters).
NEXPLOY_RUNNER_NAME container hostname Name displayed in the Nexploy UI.
NEXPLOY_RUNNER_LABELS empty Comma-separated labels used by Nexploy to target this runner, e.g. arm64,gpu.
NEXPLOY_RUNNER_CONCURRENCY 2 Maximum number of builds running at once. Jobs beyond this are rejected so the server can reroute them.
NEXPLOY_RUNNER_WORK_DIR /workspace Where clones live. One directory per repository and job, removed after each build.
NEXPLOY_RUNNER_JOB_TIMEOUT_MS 3600000 Hard ceiling per job. The server may send a shorter timeout per job.
NEXPLOY_RUNNER_KEEP_WORKDIR false Keep the clone after the build. Debugging only — clones contain repository source and .env material.
NEXPLOY_RUNNER_PRUNE_AFTER_BUILD true Prune dangling images after each build to keep the build host's disk in check.
NEXPLOY_RUNNER_ALLOW_INSECURE false Allow a plain-HTTP NEXPLOY_URL on a remote host. Off by default because the token and registry credentials cross the wire.
NEXPLOY_RUNNER_TLS_REJECT_UNAUTHORIZED true Set to false only for a Nexploy server behind a private CA you cannot install.
NEXPLOY_RUNNER_HEALTH_PORT 9090 Health endpoint port. 0 disables it.
DOCKER_SOCKET_PATH /var/run/docker.sock Docker socket used for builds.
DOCKER_HOST unset Use a TCP daemon instead of the socket, e.g. tcp://127.0.0.1:2375.
LOG_LEVEL info fatal, error, warn, info, debug, trace.

Health

  • GET /healthz — process is alive (always 200 while the runner runs).
  • GET /readyz — 200 when registered with Nexploy, 503 while reconnecting.

Both return the current state as JSON:

{ "connected": true, "runnerId": "rnr_...", "activeJobs": 1, "maxConcurrency": 2, "draining": false }

What a job does

  1. Clone — shallow clone of the branch, optional commit checkout and submodules. Credentials come from Nexploy per job and are never written to disk; if the token expired mid-flight the runner asks Nexploy for a fresh one and retries once.
  2. Build — docker build against the local daemon with the build args, labels, target stage, platform and cache sources sent by Nexploy. .dockerignore in the build context is honoured, so oversized contexts never get packed.
  3. Push — tags and pushes to the registry Nexploy selected, reporting the resulting digest.
  4. Cleanup — workspace removed, the local copy of the pushed image removed, dangling images pruned.

Every log line streams back to Nexploy in near real time and shows up in the normal build log UI. Cancelling a build in Nexploy aborts the clone, the build and the push on the runner.

If a job carries no registry, the image stays on the build host and the runner says so in the log — that combination is only useful when the build host is the deployment target.


Operating notes

  • Disk. Builds are disk-hungry: clones, layer cache and pushed images all live on the build host. Give /workspace and /var/lib/docker real room, and keep NEXPLOY_RUNNER_PRUNE_AFTER_BUILD on.
  • Docker socket access is root-equivalent on the build host. Run runners on machines dedicated to building, not next to production workloads you care about.
  • Restarts. On shutdown the runner stops accepting jobs and drains in-flight builds for up to 5 minutes before cancelling them. Messages produced while disconnected are buffered and replayed on reconnect, so a short network blip does not lose a build result.
  • Multiple servers. Run one container per Nexploy server, each with its own token, name and workspace volume.

Development

pnpm install
pnpm dev          # watch mode against a local Nexploy
pnpm test         # unit tests
pnpm typecheck
pnpm check        # biome format + lint
pnpm build

The wire format between the runner and Nexploy — and everything the server side must implement — is specified in PROTOCOL.md.

License

GPL-3.0