Merge pull request #36 from archdex-art/fix/drop-syntax-directive

fix(deploy): drop the `# syntax=` directive — it is what fails on Render

Author: archdex-art

.github/workflows/publish-image.yml

@@ -0,0 +1,80 @@
+name: Publish image
+
+# Build the production image ONCE, in the place that already proves it works, and publish it.
+#
+# WHY THIS EXISTS. Every deploy failure this project has had was a build-input problem on the
+# platform, not a code problem: a stale Root Directory, a Dockerfile Path pointing at a moved
+# file, and an external BuildKit frontend that could not re-resolve the Dockerfile. None of
+# them was reproducible by `docker build .`, and none of them could happen at all if the
+# platform were not building.
+#
+# A service that PULLS this image has no Dockerfile path, no build context, no root directory
+# and no frontend — the entire class of failure is gone, and the image running in production
+# is bit-for-bit the one CI built, indexed two real repositories with, and gated at 85% of the
+# 512MB budget. See apps/web/DEPLOY.md, "Deploying the prebuilt image".
+#
+# linux/amd64 only: that is what Render runs. Building the arm64 variant as well would double
+# the job time to publish an image nothing pulls.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  # A newer commit's image supersedes an older one; there is no value in publishing both.
+  group: publish-image
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    name: Build and push to GHCR
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      # Path resolution first, exactly as the smoke-test job does. It costs five seconds and
+      # it is the check that four failed deploys were missing.
+      - name: Verify every dockerfile path resolves
+        run: ./scripts/verify-docker.sh --paths
+
+      - name: Log in to GHCR
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
+
+      # Plain buildx rather than a third-party action: this workflow can push to the org's
+      # package registry, so the fewer external actions in its supply chain the better.
+      #
+      # Two tags, and both matter. `:latest` is what a service pulls; the commit SHA is what
+      # makes a rollback possible and what tells you which image is actually running — Render
+      # caches mutable tags, so a SHA tag is also the only way to force a specific image.
+      - name: Build and push
+        run: |
+          set -euo pipefail
+          REPO="ghcr.io/$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')"
+          docker buildx build \
+            --platform linux/amd64 \
+            --tag "$REPO:latest" \
+            --tag "$REPO:${{ github.sha }}" \
+            --label "org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}" \
+            --label "org.opencontainers.image.revision=${{ github.sha }}" \
+            --push \
+            .
+          echo "published $REPO:latest and $REPO:${{ github.sha }}"
+
+      - name: Summary
+        run: |
+          REPO="ghcr.io/$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')"
+          {
+            echo "### Image published"
+            echo
+            echo '```'
+            echo "$REPO:latest"
+            echo "$REPO:${{ github.sha }}"
+            echo '```'
+            echo
+            echo "A Render service using **Existing Image** with the URL above has no Dockerfile"
+            echo "path, no build context and no root directory to get wrong."
+          } >> "$GITHUB_STEP_SUMMARY"

Dockerfile

@@ -1,6 +1,25 @@
-# syntax=docker/dockerfile:1
-#
 # THE IMAGE FOR apps/web, BUILT FROM THE MONOREPO ROOT.
+#
+# NO `# syntax=` DIRECTIVE, DELIBERATELY, AND IT MUST NOT COME BACK WITHOUT READING THIS.
+#
+# That directive tells BuildKit to fetch an EXTERNAL frontend image and hand the build to it,
+# and that frontend resolves the Dockerfile ITSELF rather than using the definition BuildKit
+# already loaded. On Render that second resolution is what failed, every time, for five
+# deploys — the logs show step #1 succeeding and then the solve dying:
+#
+#   #1 [internal] load build definition from Dockerfile
+#   #1 transferring dockerfile: 9.55kB done          <- this file, read correctly
+#   #1 DONE 0.0s
+#   error: failed to solve: failed to read dockerfile: open Dockerfile : no such file or directory
+#
+# The same invocation locally (`docker build -f apps/web/Dockerfile .`) prints the identical
+# step name and the identical 9.55kB and then BUILDS, because the local builder resolves the
+# frontend differently. That divergence is the whole bug, and it is not reachable from the
+# Dockerfile's own content — only from whether an external frontend is involved at all.
+#
+# The directive bought this file NOTHING: it uses no BuildKit-frontend feature — no
+# `RUN --mount`, no heredocs, no `COPY --link`, no `COPY --chmod`. Checked before removing it,
+# and `scripts/verify-docker.sh` re-checks every path that can invoke this build.
 #   docker build -t codegraph .
 #
 # It lives HERE, beside the lockfile, rather than in apps/web, because the repo root is the

apps/web/DEPLOY.md

@@ -118,6 +118,47 @@ The other Free-tier consequence is speed: 0.1 CPU against the 0.5 the smoke test
 holds; indexing simply takes proportionally longer, and the worker's shutdown drain is why
 `maxShutdownDelaySeconds` is raised.
 
+#### Deploying the prebuilt image (the way that cannot break on paths)
+
+Every deploy failure this project has had was a **build-input** problem on the platform, not a
+code problem: a stale Root Directory, a Dockerfile Path pointing at a moved file, and an
+external BuildKit frontend that could not re-resolve the Dockerfile. None of them was
+reproducible by `docker build .`, and **none of them can happen if the platform is not
+building.**
+
+`.github/workflows/publish-image.yml` builds the image on every push to `main` — in the same
+CI that already indexes two real repositories with it and gates peak memory at 85% of the
+512 MB budget — and pushes it to GHCR:
+
+```
+ghcr.io/archdex-art/codegraph:latest
+ghcr.io/archdex-art/codegraph:<commit-sha>
+```
+
+A service that PULLS that image has no Dockerfile path, no build context, no root directory
+and no frontend. The image running in production is bit-for-bit the one CI verified, which is
+not true today — Render currently rebuilds from source and can produce a different image from
+the one that passed.
+
+**One-time setup:**
+
+1. Push to `main` once so the workflow publishes the first image.
+2. GitHub → the repo → *Packages* → `codegraph` → *Package settings* → **change visibility to
+   Public**. Packages pushed with `GITHUB_TOKEN` are private by default even in a public repo,
+   and a private image needs a Render *Registry Credential* instead.
+3. Render → *New* → *Web Service* → **Existing Image** → image URL
+   `ghcr.io/archdex-art/codegraph:latest`.
+4. Set the environment variables from the table below, the health check path `/api/health`,
+   and — if you want persistence — a Starter instance with a disk at `/app/data`.
+5. Delete the old repo-backed service once the new one serves traffic.
+
+Deploy by clicking *Manual Deploy* (or hitting the Deploy Hook from CI) after a publish. Pin
+the SHA tag rather than `latest` when you need certainty about which image is running: Render
+caches mutable tags, so `latest` can serve a stale image.
+
+The Dockerfile-based path stays fully supported and is what `docker compose` and CI use; this
+is about which of the two the *production service* depends on.
+
 #### Before you push a Docker change
 
 ```bash

apps/web/Dockerfile

@@ -1,6 +1,25 @@
-# syntax=docker/dockerfile:1
-#
 # THE IMAGE FOR apps/web, BUILT FROM THE MONOREPO ROOT.
+#
+# NO `# syntax=` DIRECTIVE, DELIBERATELY, AND IT MUST NOT COME BACK WITHOUT READING THIS.
+#
+# That directive tells BuildKit to fetch an EXTERNAL frontend image and hand the build to it,
+# and that frontend resolves the Dockerfile ITSELF rather than using the definition BuildKit
+# already loaded. On Render that second resolution is what failed, every time, for five
+# deploys — the logs show step #1 succeeding and then the solve dying:
+#
+#   #1 [internal] load build definition from Dockerfile
+#   #1 transferring dockerfile: 9.55kB done          <- this file, read correctly
+#   #1 DONE 0.0s
+#   error: failed to solve: failed to read dockerfile: open Dockerfile : no such file or directory
+#
+# The same invocation locally (`docker build -f apps/web/Dockerfile .`) prints the identical
+# step name and the identical 9.55kB and then BUILDS, because the local builder resolves the
+# frontend differently. That divergence is the whole bug, and it is not reachable from the
+# Dockerfile's own content — only from whether an external frontend is involved at all.
+#
+# The directive bought this file NOTHING: it uses no BuildKit-frontend feature — no
+# `RUN --mount`, no heredocs, no `COPY --link`, no `COPY --chmod`. Checked before removing it,
+# and `scripts/verify-docker.sh` re-checks every path that can invoke this build.
 #   docker build -t codegraph .
 #
 # It lives HERE, beside the lockfile, rather than in apps/web, because the repo root is the

apps/web/tests/readme-claims.test.ts

@@ -200,10 +200,36 @@ describe("the deploy's two dockerfile paths both resolve", () => {
     // that the P1 monorepo move broke by leaving the dockerfile at `apps/web/Dockerfile` while
     // the context became the repo root.
     const rootDockerfile = readFileSync(path.join(root, "Dockerfile"), "utf8");
-    expect(rootDockerfile).toMatch(/^# syntax=docker\/dockerfile:1/);
     expect(rootDockerfile).toMatch(/ENV CG_USE_WORKER=true/);
   });
 
+  it("carries no `# syntax=` directive, so no external frontend re-reads the dockerfile", () => {
+    // This assertion was written the other way round — requiring the directive — and this
+    // suite failed the moment it was removed. Kept, inverted, because the removal is the fix
+    // for the fifth failed deploy and nothing in the file's content would reveal that:
+    //
+    //   #1 [internal] load build definition from Dockerfile
+    //   #1 transferring dockerfile: 9.55kB done      <- read correctly, right size
+    //   #1 DONE 0.0s
+    //   error: failed to solve: failed to read dockerfile: open Dockerfile : no such file
+    //
+    // `# syntax=` hands the build to an EXTERNAL frontend image which resolves the dockerfile
+    // itself instead of using the definition BuildKit already loaded, and on Render that
+    // second resolution failed. The directive bought this file nothing: no `RUN --mount`, no
+    // heredocs, no `COPY --link`, no `COPY --chmod`. Adding it back means re-introducing the
+    // failure, so it fails here first.
+    const rootDockerfile = readFileSync(path.join(root, "Dockerfile"), "utf8");
+    expect(rootDockerfile).not.toMatch(/^#\s*syntax\s*=/m);
+    // ...and the features that would justify bringing it back are absent, so the removal
+    // stays safe. Comment lines are stripped first: the header above NAMES those features in
+    // prose, and the first version of this assertion matched its own explanation.
+    const instructions = rootDockerfile
+      .split("\n")
+      .filter((line) => !line.trim().startsWith("#"))
+      .join("\n");
+    expect(instructions).not.toMatch(/RUN\s+--mount|COPY\s+--link|COPY\s+--chmod|<<[A-Z]/);
+  });
+
   it("keeps apps/web/Dockerfile byte-identical to it", () => {
     // THE failure mode of a duplicate is drift: two build definitions, one of them edited, and
     // a deploy built from whichever the platform happened to read. Byte equality is the whole

render.yaml

@@ -41,6 +41,18 @@ services:
     dockerfilePath: ./Dockerfile
     dockerContext: .
     #
+    # THE WAY THAT CANNOT BREAK ON PATHS. Every failed deploy here was a build-input problem,
+    # and none of them is reachable by a service that does not build. CI publishes the exact
+    # image it smoke-tests to ghcr.io on every push to main
+    # (.github/workflows/publish-image.yml), so this whole block can be replaced by:
+    #
+    #     runtime: image
+    #     image:
+    #       url: ghcr.io/archdex-art/codegraph:latest
+    #
+    # and then there is no dockerfilePath, no dockerContext and no rootDir to get wrong.
+    # Setup steps are in apps/web/DEPLOY.md, "Deploying the prebuilt image".
+    #
     # `apps/web/Dockerfile` is a byte-identical COPY of that file, kept in step by a test, so
     # a service whose dashboard still carries the old Dockerfile Path reads real content
     # instead of the two bytes an absent file produces. Remove the copy once the dashboard

scripts/verify-docker.sh

@@ -113,19 +113,56 @@ pass "image builds"
 docker run -d --name "$NAME" --memory=512m --memory-swap=512m --cpus=0.5 -p 4599:4000 "$TAG" >/dev/null \
   || fail "container did not start"
 
+# NO `... | grep -q` ANYWHERE BELOW, and that is not style. Under `set -o pipefail` — set at
+# the top of this file, correctly — `grep -q` exits the instant it matches, the writer upstream
+# gets SIGPIPE, and the PIPELINE reports 141. So the check fails exactly when the string is
+# found EARLY with output still to come, and passes when the output is short enough to finish
+# writing first. Measured here: three consecutive runs of the same green image went pass,
+# fail, fail, each failure dumping logs that visibly contained the string it had just failed
+# to find. Capturing first and matching in the shell has no pipe and no race.
+logs_of() { docker logs "$1" 2>&1 || true; }
+
 for _ in $(seq 1 40); do
   if curl -fsS -m 3 http://127.0.0.1:4599/api/health >/dev/null 2>&1; then break; fi
   sleep 1
 done
-curl -fsS -m 5 http://127.0.0.1:4599/api/health | grep -q '"status":"ok"' \
-  || { docker logs "$NAME" 2>&1 | tail -20 >&2; fail "/api/health did not report ok under 512MB/0.5cpu"; }
-pass "/api/health reports ok under --memory=512m --cpus=0.5"
+health=$(curl -fsS -m 5 http://127.0.0.1:4599/api/health 2>/dev/null || true)
+case "$health" in
+  *'"status":"ok"'*) pass "/api/health reports ok under --memory=512m --cpus=0.5" ;;
+  *) logs_of "$NAME" | tail -20 >&2; fail "/api/health did not report ok under 512MB/0.5cpu (got: ${health:-no response})" ;;
+esac
 
 # The worker is what claims queued jobs. With CG_USE_WORKER=true baked into the image and no
 # worker running, every index would sit in the queue forever while the app looked healthy —
 # the failure mode the entrypoint refuses to boot into, asserted here too.
-docker logs "$NAME" 2>&1 | grep -q "worker started" \
-  || { docker logs "$NAME" 2>&1 | tail -20 >&2; fail "the analysis worker did not start"; }
-pass "analysis worker started"
+#
+# TWO SIGNALS, because they fail differently and a gate that cannot tell them apart is a gate
+# people re-run instead of read:
+#
+#   · `entrypoint: starting analysis worker` is printed synchronously by the entrypoint before
+#     the web server is launched at all. Absent => the worker was never launched, which is a
+#     real defect in the image.
+#   · `worker started` is the worker's own line, emitted only after it opens SQLite and runs
+#     migrations — which can land well AFTER /api/health is already answering. Absent while
+#     the first line is present => slow start, not a broken image.
+worker_wait=0
+while :; do
+  container_logs=$(logs_of "$NAME")
+  case "$container_logs" in *"worker started"*) break ;; esac
+  [ "$worker_wait" -ge 60 ] && break
+  worker_wait=$((worker_wait + 1))
+  sleep 1
+done
+
+case "$container_logs" in
+  *"entrypoint: starting analysis worker"*) : ;;
+  *) printf '%s\n' "$container_logs" | tail -20 >&2
+     fail "the entrypoint never launched the worker (is CG_USE_WORKER=true in the image?)" ;;
+esac
+case "$container_logs" in
+  *"worker started"*) pass "analysis worker started (after ${worker_wait}s)" ;;
+  *) printf '%s\n' "$container_logs" | tail -20 >&2
+     fail "the worker was launched but never reported ready (waited ${worker_wait}s)" ;;
+esac
 
 printf '\n%sall docker paths resolve and the image serves%s\n' "$GREEN" "$OFF"