From 45bf28412a5ff4d8d7d2ed32c2aa4855dcd24c2d Mon Sep 17 00:00:00 2001 From: trivedi-vatsal Date: Sat, 29 Aug 2026 10:44:35 +0530 Subject: [PATCH] Document docker.sock workspace path translation for runtime: jobs. Co-authored-by: Cursor --- src/content/docs/adr/004-docker-executor.md | 4 +++- src/content/docs/start/configuration.md | 1 + src/content/docs/understanding/deployment.md | 7 +++++++ src/content/docs/using/troubleshooting.md | 14 ++++++++++++++ 4 files changed, 25 insertions(+), 1 deletion(-) diff --git a/src/content/docs/adr/004-docker-executor.md b/src/content/docs/adr/004-docker-executor.md index 7b088ad..59fe2c6 100644 --- a/src/content/docs/adr/004-docker-executor.md +++ b/src/content/docs/adr/004-docker-executor.md @@ -40,7 +40,9 @@ UUID" job API. The remote-host path is whatever Docker already understands - The worker image ships `docker-cli`. Compose mounts `/var/run/docker.sock` and adds the socket's group (`DOCKER_GID`) so uid 10001 can talk to the - engine. Job containers still do not see that socket. + engine. Job containers still do not see that socket. Volume sources passed + to `docker run` are host paths: `/proc/self/mountinfo` (or `CI_WORKSPACE_HOST`) + translates `WORKSPACE_DIR` when this process is a container. - Operators who never set `runtime:` and never enable fork PRs still run as before, as a process. - A Coolify API token cannot replace `CI_DOCKER_HOST`. Remote jobs are Docker diff --git a/src/content/docs/start/configuration.md b/src/content/docs/start/configuration.md index bc84d67..f6dc5e5 100644 --- a/src/content/docs/start/configuration.md +++ b/src/content/docs/start/configuration.md @@ -35,6 +35,7 @@ The UI caps the field at 32. The API does not. | `CI_PUBLIC_BASE_URL` | no | Seeds the public base URL on first boot only; the UI owns it afterwards. | | `CI_BOOTSTRAP_ADMIN_PASSWORD` | no | Creates the `admin` user on first boot so a headless deploy can be driven over the API. Ignored once a user exists. | | `CI_DOCKER_HOST` | no | Docker engine for `runtime:` and fork PRs. Falls back to `DOCKER_HOST`, then the engine default (typically the mounted socket). | +| `CI_WORKSPACE_HOST` | no | Host path that corresponds to `WORKSPACE_DIR`, used as the `docker run -v` source. Needed only when mount-table translation is wrong (unusual volume drivers, or a remote engine). | | `LISTEN_ADDR` | no | Default `:8080`. | | `DATA_DIR` | no | Default `/data`: `ci.db` and `logs/`. Must be a persistent volume. | | `WORKSPACE_DIR` | no | Default `/workspace`: per-job checkouts, disposable. | diff --git a/src/content/docs/understanding/deployment.md b/src/content/docs/understanding/deployment.md index bfe9187..b0fa254 100644 --- a/src/content/docs/understanding/deployment.md +++ b/src/content/docs/understanding/deployment.md @@ -42,6 +42,13 @@ VM, and the host path is a symlink into `~/.docker`, so the host's `stat` reports an unrelated group. Set `DOCKER_GID=0` there and recreate the container. +When this process is itself a container and `docker.sock` is the host engine, +`docker run -v` must use the **host** path for `WORKSPACE_DIR` (the directory +behind `/workspace` in `/proc/self/mountinfo`). The worker rewrites that +itself. If a `runtime:` job logs `runtime … via docker` then fails because +`package-lock.json` is missing, the rewrite missed: set `CI_WORKSPACE_HOST` +to the host directory mounted at `WORKSPACE_DIR` and recreate. + Nothing else needs this. The service boots and reports checks with an unreachable socket; only `runtime:` jobs and fork PRs fail. Job containers never receive that socket; see [ADR 004](/adr/004-docker-executor/). diff --git a/src/content/docs/using/troubleshooting.md b/src/content/docs/using/troubleshooting.md index 89b891f..e3a54c0 100644 --- a/src/content/docs/using/troubleshooting.md +++ b/src/content/docs/using/troubleshooting.md @@ -72,6 +72,20 @@ need process execution. See [Pipelines](/using/pipelines/). +## `runtime:` job has an empty `/work` + +**Cause:** The worker is a container using the host `docker.sock`. `docker run +-v /workspace/…:/work` is interpreted on the **host**, where that path does +not hold the checkout. `npm ci` then fails with a missing `package-lock.json` +(or the job looks like it cloned nothing). + +**Fix:** Upgrade to a build that rewrites the volume source from +`/proc/self/mountinfo`. If that still misses, set `CI_WORKSPACE_HOST` to the +host directory mounted at `WORKSPACE_DIR` and recreate the container. + +See [Deployment](/understanding/deployment/) and +[Configuration](/start/configuration/). + ## Permission denied on the docker socket **Cause:** `DOCKER_GID` does not match the host socket's group. The image runs