Document docker.sock workspace path translation

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

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. |

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/).

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