docs: correct compose comments that still describe Convex - #3188
Merged
Conversation
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
force-pushed
the
docs/describe-postgres-backend-v2
branch
from
September 3, 2026 17:40
660b32a to
44ff637
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The shipped
compose.ymlexplains itself to operators, and eleven of itscomments 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.
tale_appis migrated by the backend at boot, somigrations/db/is empty and the role is a no-opservices/db/README.md@tanstack/react-startdependency existsservices/platform/package.jsonSANDBOX_BROWSER_VIEWto Convexservices/sandbox/src/types.ts,services/sandbox-runtime/entrypoint.shTALE_ROLE, and there is no Convex workservices/platform/docker-entrypoint.sh:133BACKEND_UPSTREAMis the "Convex→Postgres cutover switch"services/proxy/docker-entrypoint.sh:122KNOWLEDGE_DATABASE_URL"backend/core/knowledge/pool.tsThe
BACKEND_UPSTREAMblock already carried a correct paragraph directlybelow 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.tsin the CLI's db-service comment.The docs image's dockerignore still lists
services/convex/. Removing thatdead line is a no-op for the build, but
services/*/Dockerfile.dockerignoreis a trigger path for
security.yml— so a one-line comment cleanup pulled inBun auditand the Trivy filesystem scan, and both are red for reasons thathave 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-datavolume keeps itsname, which is load-bearing — renaming it would make every existing operator
migrate a volume. The fourth,
Convex _storage retired, is a historical noteabout 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:
tale-knowledge-db. That isthe repo's local-dev
compose.yml. Thetale deploystack is generated bythe CLI, has no separate knowledge service, and reaches the corpus through a
knowledge-dbnetwork alias ondb— which is what main's page alreadysays.
tools/cli/src/lib/compose/services/create-db-service.tsstates itoutright: "The single-node CLI stack has no separate
knowledge-dbservice."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 configvalid,oxfmt --checkclean, the CLIcompose suite 47 pass / 0 fail (
bun test src/lib/compose— these usebun:test, not vitest).A finding worth its own issue
Touching that dockerignore triggered
security.yml, which gates on HIGH andCRITICAL production advisories — and it fails: Faker (
GHSA-qxc2-j82w-r537),MySQL2 auth-plugin downgrade (
GHSA-3f6p-5ww8-...), and threefast-uriSSRF/host-confusion advisories.
That workflow only runs when
bun.lock, apackage.json, aDockerfile, aDockerfile.dockerignore,.trivyignore.yaml, or the workflow itselfchanges. 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 aDockerfile).
Both belong in their own change — a dependency bump with real compatibility
questions — not in a comment pass.