Skip to content

docs: correct compose comments that still describe Convex - #3188

Merged
Israeltheminer merged 1 commit into
mainfrom
docs/describe-postgres-backend-v2
Sep 3, 2026
Merged

docs: correct compose comments that still describe Convex#3188
Israeltheminer merged 1 commit into
mainfrom
docs/describe-postgres-backend-v2

Conversation

@Israeltheminer

@Israeltheminer Israeltheminer commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

The shipped compose.yml explains itself to operators, and eleven of its
comments still describe the retired Convex runtime. Comments have no runtime
effect, which is exactly why they went stale — nothing fails when they are
wrong, so the operator reading the file is the one who pays.

Each is replaced with what the file actually does now, verified against the
code rather than reworded.

Comment said Verified truth Source
the auth schema is "owned by Convex, not dbmate" tale_app is migrated by the backend at boot, so migrations/db/ is empty and the role is a no-op services/db/README.md
platform is "TanStack Start + Convex" a Vite + TanStack Router SPA served by Bun; no @tanstack/react-start dependency exists services/platform/package.json
the entrypoint pushes SANDBOX_BROWSER_VIEW to Convex nothing pushes it — the sandbox spawner and the sandbox runtime each read it services/sandbox/src/types.ts, services/sandbox-runtime/entrypoint.sh
the entrypoint "dispatches before any Convex work" it dispatches on TALE_ROLE, and there is no Convex work services/platform/docker-entrypoint.sh:133
BACKEND_UPSTREAM is the "Convex→Postgres cutover switch" an override for split deployments; an unset value 404s the machine doors rather than falling back services/proxy/docker-entrypoint.sh:122
"Convex node-actions connect here via KNOWLEDGE_DATABASE_URL" the backend connects, pooled backend/core/knowledge/pool.ts
"internal traffic uses ... the internal Convex URL" Docker service names
"Convex reaches the spawner" the backend does

The BACKEND_UPSTREAM block already carried a correct paragraph directly
below the stale one, so that fix is a deletion. One sentence had also been
left truncated mid-clause ("replaces the" → nothing) when the parallel-build
note was cut.

Also drops a reference to a path deleted with the Convex tree:
convex/lib/knowledge/db/knowledge_db.ts in the CLI's db-service comment.

The docs image's dockerignore still lists services/convex/. Removing that
dead line is a no-op for the build, but services/*/Dockerfile.dockerignore
is a trigger path for security.yml — so a one-line comment cleanup pulled in
Bun audit and the Trivy filesystem scan, and both are red for reasons that
have nothing to do with this PR (see below). Left for whoever fixes them.

What is deliberately kept

Three mentions stay. They explain why the convex-data volume keeps its
name, which is load-bearing — renaming it would make every existing operator
migrate a volume. The fourth, Convex _storage retired, is a historical note
about why S3 is the only blob backend.

This replaces #3150, and does not carry its docs diff

#3150 set out to align the self-hosted docs with the Postgres backend. #3154
has since done that, and #3150's version is now behind main on two facts:

  • It describes eleven containers with a separate tale-knowledge-db. That is
    the repo's local-dev compose.yml. The tale deploy stack is generated by
    the CLI, has no separate knowledge service, and reaches the corpus through a
    knowledge-db network alias on db — which is what main's page already
    says. tools/cli/src/lib/compose/services/create-db-service.ts states it
    outright: "The single-node CLI stack has no separate knowledge-db service."
  • It describes the platform as React + TanStack Start. Main correctly says
    Vite + TanStack Router.

Applying it would regress both. I started to "correct" main's container count
from the local-dev compose file before finding the generator, so this PR
carries none of that — main's pages are accurate and untouched here.

Out of scope

There are ~1,500 Convex mentions elsewhere in the tree — schema field names,
test fixtures, identifiers, and wire-contract keys. That is a rename epic with
real compatibility questions, not a comment pass, so nothing outside these
three files is touched.

Gate

docker compose -f compose.yml config valid, oxfmt --check clean, the CLI
compose suite 47 pass / 0 fail (bun test src/lib/compose — these use
bun:test, not vitest).

A finding worth its own issue

Touching that dockerignore triggered security.yml, which gates on HIGH and
CRITICAL production advisories — and it fails: Faker (GHSA-qxc2-j82w-r537),
MySQL2 auth-plugin downgrade (GHSA-3f6p-5ww8-...), and three fast-uri
SSRF/host-confusion advisories.

That workflow only runs when bun.lock, a package.json, a Dockerfile, a
Dockerfile.dockerignore, .trivyignore.yaml, or the workflow itself
changes. So main can accumulate advisories without any PR going red, which is
what has happened. Trivy also logs a pre-existing parse error on
services/db/Dockerfile.dockerignore (it reads a dockerignore as a
Dockerfile).

Both belong in their own change — a dependency bump with real compatibility
questions — not in a comment pass.

The shipped `compose.yml` explains itself to operators, and eleven of its
comments still describe the retired Convex runtime. They have no runtime
effect, which is exactly why they went stale — nothing fails when they
are wrong, so an operator reading the file is the one who pays.

Each is replaced with what the file actually does now, verified against
the code rather than reworded:

- The platform role's dbmate skip said the auth schema was "owned by
  Convex". `services/db/README.md` has it: `tale_app` is migrated by the
  backend at boot, so `migrations/db/` is empty and the role is a no-op.
- The platform service header said "TanStack Start + Convex". It is a
  Vite + TanStack Router SPA served by Bun; there is no `@tanstack/react-start`
  in `services/platform/package.json`.
- `SANDBOX_BROWSER_VIEW` said the entrypoint pushes it to Convex. Nothing
  pushes it: the sandbox spawner and the sandbox runtime each read it.
- The backend role said the entrypoint "dispatches before any Convex
  work". It dispatches on `TALE_ROLE`, and there is no Convex work.
- The `BACKEND_UPSTREAM` block carried the cutover-era paragraph directly
  above a correct one someone had already written below it. Dropped the
  stale half; the accurate account stays, and matches what
  `services/proxy/docker-entrypoint.sh` says about the same variable.
- The knowledge-db header credited "Convex node-actions" for the
  connection. The backend connects, pooled in `core/knowledge/pool.ts`.
- One sentence had been left truncated mid-clause ("replaces the" →
  nothing) when the parallel-build note was cut.

Also drops a reference to a path deleted with the Convex tree:
`convex/lib/knowledge/db/knowledge_db.ts` in the CLI's db-service comment.

The docs image's dockerignore still lists `services/convex/`. Removing that
dead line is a no-op for the build, but `services/*/Dockerfile.dockerignore`
is a trigger path for `security.yml`, so it drags a dependency-advisory gate
onto a comment cleanup — and that gate is currently red on main for reasons
unrelated to this change. Left for whoever fixes the advisories.

The three remaining mentions stay: they explain why the `convex-data`
volume keeps its name, which is load-bearing — renaming it would make
every existing operator migrate a volume.
@Israeltheminer
Israeltheminer force-pushed the docs/describe-postgres-backend-v2 branch from 660b32a to 44ff637 Compare September 3, 2026 17:40
@Israeltheminer
Israeltheminer merged commit 1ea4cc9 into main Sep 3, 2026
35 checks passed
@Israeltheminer
Israeltheminer deleted the docs/describe-postgres-backend-v2 branch September 3, 2026 18:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant