Repository navigation
setup: the engine brings its own database, so install asks for nothing - #2
Merged
Merged
Conversation
added 2 commits
September 20, 2026 03:18
Setup was: install PostgreSQL, create a database, enable an extension, find the role's password, write it into .env. `npm run setup` wrote DB_PASSWORD=CHANGE_ME_BEFORE_RUNNING and told the reader to edit it. That is where people stopped. Now a machine with no database gets a private PostgreSQL: binaries fetched once into the user's own data directory (not the repository, where npm ci would remove them), initdb with a password generated here that nobody types, a port nobody else is using, and a database the engine owns. An operator who sets DB_HOST/DB_USER/DB_PASSWORD keeps their own database and never comes near this. The cluster is created UTF-8 and C, not with the machine's code page: initdb on a Windows locale produces WIN1252, and migration 011 then dies on the box-drawing characters in its own comment banner — as would any source file holding a character outside that page. Details that had to be right: readiness is a query that succeeds, because an open port answers "the database system is starting up"; the server starts detached so it outlives the MCP client that started it; pg_ctl holds its log file exclusively on Windows, so nothing else may open it; and every PostgreSQL process needs its own bin directory on PATH or a Windows backend dies with 0xC0000142. MCP clients now start scripts/mcp-start.mjs, which makes sure the database is up and then becomes the bridge, so nothing has to be started by hand before the client opens.
`initdb` on a Windows locale produces a WIN1252 cluster, and migration 011 then fails on the box-drawing characters in its own comment banner: "character with byte sequence 0xe2 0x94 0x80 ... has no equivalent in encoding WIN1252". Eighteen migrations carry such characters, and so does any repository with a name or a string outside that page. The migrator now checks server_encoding before it applies anything and names the fix; doctor reports the encoding as its own check; and every createdb in the docs and both bootstrap scripts asks for UTF-8 from template0. doctor --fix wrote the same CHANGE_ME_BEFORE_RUNNING password setup used to; it provisions the database instead. The install contract — no placeholder password, a UTF-8 database, a client that starts what it needs — is pinned by a test that reads the scripts.
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.
Setup was the reason people stopped: install PostgreSQL, create a database, enable an extension, find the role's password, write it into
.env.npm run setupwroteDB_PASSWORD=CHANGE_ME_BEFORE_RUNNINGand told the reader to edit it, anddoctor --fixwrote the same.Install is now one command on a machine with nothing but Node.
git clone https://github.com/Classevelabs/context-zero-engine.git cd context-zero-engine npm run setup -- --install-mcp=claudeWhen no database is configured, the engine provisions a private PostgreSQL: binaries fetched once into the user's data directory (not the repository, where
npm ciwould remove them),initdbwith a password generated here that nobody types, a free port, and a database it owns. SettingDB_HOST/DB_USER/DB_PASSWORDkeeps your own database and never reaches this path.npm run db:status|stop|upmanage it;CONTEXTZERO_HOMEmoves it.MCP clients now start
scripts/mcp-start.mjs, which makes sure the database is running and then becomes the bridge, so nothing has to be started by hand before the client opens.A defect this surfaced:
initdbon a Windows locale produces a WIN1252 cluster, and migration 011 dies on the box-drawing characters in its own banner —character with byte sequence 0xe2 0x94 0x80 ... has no equivalent in encoding "WIN1252". Eighteen migrations carry such characters, as does any repository with a symbol or string outside that page. The provisioned cluster is UTF-8 and C; the migrator checksserver_encodingfirst and names the fix; doctor reports it; and everycreatedbin the docs and both bootstrap scripts now asks for UTF-8 fromtemplate0.Verified on Windows, first run from an empty state: provision 6.7s, start 1.3s, 33/33 migrations applied, doctor 18/18 PASS including
PostgreSQL query - scg_v2 on 18.4andDatabase migrations - 33/33. With the database stopped, a client handshake againstscripts/mcp-start.mjsreturnedcontextzero 2.15.0after the launcher started it. A WIN1252 database is refused with the message above instead of the byte-sequence error. Full suite 1945 passed, typecheck and lint clean.Details that had to be right, each one a failure first: readiness is a query that succeeds, because an open port answers "the database system is starting up"; the server starts detached so it outlives the client that started it;
pg_ctlholds its log file exclusively on Windows, so nothing else may open it; and every PostgreSQL process needs its ownbinon PATH or a Windows backend dies with0xC0000142.