Native jobs on Docker
Development preview
This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.
This recipe runs the coordinator, credential-free discovery worker, provider and container adapter on one Linux Docker host. Each job runs in a fresh sibling container. No KVM or privileged DinD sidecar is required. This is the explicitly weak, trusted-code tier; hardware VM isolation remains the default elsewhere. Read execution and secret authorization before opting in. For untrusted public PR jobs, use the native coordinator with a VM provider.
Use docker-compose.native-local.yml alone. Do not merge it with any other Compose recipe. The adapter alone receives the Docker socket and therefore has the daemon's administrative authority. Coordinator, discovery, provider and jobs receive no Docker socket. Each service has a separate UID; only private discovery and adapter sockets are shared with their clients. Provider and coordinator identities live in distinct persistent volumes. Jobs receive only authorized job inputs and secrets, never those identities or service volumes.
Requirements and image preparation
Use a Linux Docker host with Compose v2.24.0 or later, cgroup v2, and working CPU, memory/swap and process limits. Use a dedicated execution filesystem with enough reserve for images and simultaneous writable job layers; there is no portable per-job disk quota. The recipe allocates four CPUs and 8 GiB RAM per job, matching the coordinator baseline; leave additional capacity for the host and services. If you reduce the adapter limits, also lower the coordinator's NGIT_CI_PROVIDER_REQUIREMENT_DEFAULTS in a Compose override or request smaller resources in every job. Restrict repository intake as described in the authorization guide. Outbound access to your Git servers, relays, Blossom and Nix substituters must work from both service and job containers. Job bridge networking can reach LAN services. Docker Desktop and DinD are not qualified by this recipe. For LXC, see the separate Proxmox qualification.
Build the two images from the same checkout on a Linux machine with Nix flakes:
sh
nix build .#native-service-image -o result-native-services
nix build .#weak-container-image -o result-native-jobs
docker load -i result-native-services
docker load -i result-native-jobs
docker image inspect ngit-ci-weak-container:latest --format '{{.Id}}'Nix is needed to build the images, not on the execution host. You can transfer these image archives to another host and load them there. Select the host's native architecture (x86_64-linux or aarch64-linux). The job image is configured by immutable local image ID with pulling disabled. Keep the archives or record both image IDs for rollback; the service image also accepts an immutable ID.
Initialize identities and configure trust
Keep a stable Compose project name so upgrades reuse the same volumes:
sh
export COMPOSE_PROJECT_NAME=ngit-native
cp deploy/docker/native-local.env.example native-local.env
chmod 600 native-local.env
docker compose --env-file native-local.env -f docker-compose.native-local.yml \
run --rm --no-deps --entrypoint ngit-ci-container-identity coordinator coordinator
docker compose --env-file native-local.env -f docker-compose.native-local.yml \
run --rm --no-deps --entrypoint ngit-ci-container-identity provider providerEach command creates an identity only when absent and prints its public key. Record those as NGIT_CI_COORDINATOR_PUBLIC_KEY and NGIT_CI_PROVIDER_PUBLIC_KEY. Do not copy the private keys into environment files or argv. Back up both volumes. An existing coordinator identity can instead be restored while all coordinators using it are stopped; preserve its queue and deduplication data as well.
Edit native-local.env: replace every placeholder, set the job image ID and DOCKER_GROUP_ID to stat -c %g /var/run/docker.sock, then configure repository, relays and Blossom. The same relays are used for coordinator discovery and provider advertisements/inbox. They must accept those event kinds. A reachable Blossom server is required even for jobs without artifacts because providers publish an environment description. Use your own services or ones whose policies permit use.
NGIT_CI_WEAK_CONTAINERIZATION=true explicitly enables the tier at all three execution participants. NGIT_CI_WEAK_CONTAINERIZATION_AUTHORIZATION grants a specific signer standing authority for code from the exact repository coordinate. Neither a service request nor repository ownership grants arbitrary contributors permission to execute. Keep the default request-required policy and authorize the coordinator through the repository's normal Service Request workflow.
sh
docker compose --env-file native-local.env -f docker-compose.native-local.yml config --quiet
docker compose --env-file native-local.env -f docker-compose.native-local.yml up -d
docker compose --env-file native-local.env -f docker-compose.native-local.yml logs -fThe socket health checks order startup; they are not proof that a provider has published an advertisement or that a job can run. Verify the provider advertisement and complete First native run before migrating.
Enable secrets separately
First validate without secrets. To enable otherwise-authorized secrets, set:
dotenv
NGIT_CI_WEAK_CONTAINERIZATION_ALLOW_SECRETS=true
NGIT_CI_PROVIDER_WEAK_ALLOW_SECRETS=true
NGIT_CI_PROVIDERS_ALLOWED_SECRETS=YOUR_PROVIDER_PUBLIC_KEYAdd the repository alias to NGIT_CI_REPOS and put its secret values in ngit-ci-secrets.env beside the Compose file, mode 0600, using the existing NGIT_CI_SECRET_<ALIAS>__<NAME> convention. This file goes only to the coordinator. Existing maintainership/trigger restrictions still apply; ordinary PR runs do not gain secrets. See secret authorization.
Recreate coordinator and provider after changing their configuration. Drain active work before revoking grants: configuration changes cannot retract an allocation already delivered. Treat all authorized job code and dependencies as trusted with any secrets you release to it.
Persistence, upgrades and recovery
The five named volumes hold coordinator state/identity, discovery socket, provider state/identity, adapter cleanup records/identity and adapter socket. Keep the coordinator, provider and adapter data volumes across upgrades. docker compose down retains them; down -v destroys identities, deduplication and cleanup evidence and is not an upgrade command.
Stop admission and drain jobs before stopping services. Dependency order stops the provider before the adapter and coordinator before discovery. The 35-minute stop grace assumes default job timeouts; raise it if your configured timeout plus finalization exceeds it. Rebuild/load both images, update image IDs, then recreate the services. Retain old images until the new stack completes a test job.
After abrupt adapter termination, inspect retained cleanup records and the adapter-labelled job containers before restarting. Follow cleanup recovery; never clear records just to bypass a startup refusal. Restart the provider after adapter recovery, preserving its durable allocation records. Do not resubmit a job until its existing attempt's outcome and cleanup are understood.
This recipe explicitly disables the managed provider cache. Jobs can still use public Nix substituters, but each has a fresh store. Enabling a managed cache is separate work requiring the dedicated cache worker, its credential separation and job-reachable URL; do not simply set NGIT_CI_PROVIDER_MANAGED_CACHE=true.
Migration from v0.1.1
Convert workflows to .grasp/nix and validate them before stopping your act coordinator. This recipe has --act-runner none and will not execute act YAML. Create a new project for validation; keep the old deployment stopped when transferring an identity. The former coordinator Docker socket is unnecessary: the adapter owns that connection. A former DinD sidecar is unnecessary on a suitable Docker host. For nested Docker/LXC installations, consult the migration choices rather than assuming equivalent support.
Qualification record
Validated on 2026-10-29 in a disposable x86_64 NixOS VM using rootful Docker 29.9.1, Compose 5.6.0, cgroup v2 and overlayfs. The shipped Compose stack passed secret-consent denial, signed native results with downloaded artifacts, identity and state persistence across service restarts without duplicate allocations, and rejection of a PR signer without an execution grant. The adapter lifecycle test passed fresh filesystem/private-input checks, observed cgroup memory exhaustion, subsequent job recovery and forced cancellation/cleanup.
This qualifies that Linux Docker configuration, not every compatible daemon or architecture. Docker Desktop, rootless Compose and DinD remain unqualified. The Proxmox guide records the separate unprivileged LXC qualification. Disk-exhaustion recovery and portable per-job writable-layer quotas are not established by these tests. See the reproducible test setup.