[dex-the-ai]

Closes #261

Problem

The README only described Capella. A new user who wanted to run the quickstart against a local Couchbase Server got one appendix paragraph. It had no commands, didn't list the bucket, scope, and collections the app expects, and gave no way to confirm the app could actually reach Couchbase. Because the app connects lazily, the API started log line appears even when the database is unreachable.

Change (README only)

Scope follows @ejscribner's comment on the issue: local setup, required env vars, expected bucket/scope/collection setup, and a verification check.

• New section, "Running Against a Local Couchbase Server": six steps.
  1. docker run Couchbase Server.
  2. couchbase-cli cluster-init with the Data, Query, and Index services, with the reason each one is needed.
  3. Load travel-sample through the REST API, with the web console as an alternative.
  4. Check that the inventory scope exists, plus a table of the keyspaces the app uses (travel-sample / inventory / airline, airport, route).
  5. dev.env and test.env values for local use, including the couchbase:// vs couchbases:// pitfall.
  6. npm start.
• Env var table: each DB_* and APP_PORT variable, with its purpose and the local value, plus which file npm start and npm test read.
• Verification step: curl -i http://localhost:3000/api/v1/airline/airline_10 with the exact expected 200 body, a SQL++ list check, and troubleshooting for the failure modes I reproduced (hang/timeout, authentication failure, document not found).
• Docker note: inside the app container, localhost isn't the host (use host.docker.internal).
• Small fixes: the Capella setup section and the prerequisites now link to the new section, and the self-managed appendix points to it. The data model section said the collection was routes; the code uses route (db/connection.js).

No code, dependency, or CI changes.

Validation evidence

I followed the README against a fresh Couchbase Server 7.6.4 container (couchbase:enterprise-7.6.4, unpublished ports; the app ran in node:24 with --network container:<cb>, so couchbase://localhost resolves exactly as in the docs).

Step	Command	Exit	Output
2	couchbase-cli cluster-init -c localhost ... --services data,index,query --cluster-ramsize 1024 --cluster-index-ramsize 256 --index-storage-setting default	0	SUCCESS: Cluster initialized
3	curl -u Administrator:password -X POST http://localhost:8091/sampleBuckets/install -d '["travel-sample"]'	0	{"tasks":[{"taskId":"…","sample":"travel-sample","bucket":"travel-sample"}]}; itemCount reached 63288
4	curl -s -u … /pools/default/buckets/travel-sample/scopes | grep -o '"name":"inventory"'	0	"name":"inventory" (collections: route, landmark, hotel, airport, airline)
6	npm ci && npm start with the documented dev.env	n/a	API started at http://localhost:3000
verify	curl -i http://localhost:3000/api/v1/airline/airline_10	0	HTTP 200 {"id":10,"type":"airline","name":"40-Mile Air","iata":"Q5","icao":"MLA","callsign":"MILE-AIR","country":"United States"}
verify	curl "http://localhost:3000/api/v1/airport/list?country=United%20Kingdom&limit=2"	0	HTTP 200, 2 airports (LON, HLY)
verify	curl http://localhost:3000/swagger-ui/	0	HTTP 200
tests	npm test (reads config/test.env with the same local values)	0	Test Suites: 20 passed, 20 total / Tests: 20 passed, 20 total

Troubleshooting entries were reproduced, not guessed:

• DB_USERNAME unset: startup throws Please define the DB_USERNAME environment variable inside dev.env.
• DB_PASSWORD=wrong: the app still logs API started, then the request returns HTTP 500 AuthenticationFailureError: authentication failure.
• DB_CONN_STR=couchbase://10.255.255.1 (unreachable): the app still logs API started, then the request hangs (curl -m 30 exits 28).
• GET /api/v1/airline/does_not_exist: HTTP 404 {"message":"document not found"}.
• docker manifest inspect couchbase/server:enterprise: the image tag used in step 1 exists.

Screenshots (Playwright, captured against the running app; they're on the evidence/issue-261 branch, which can be deleted after review):

• Swagger UI at /: https://github.com/couchbase-examples/nodejs-quickstart/blob/evidence/issue-261/swagger-ui.png
• GET /api/v1/airline/airline_10: https://github.com/couchbase-examples/nodejs-quickstart/blob/evidence/issue-261/airline_10.png

Not validated live:

• The literal docker run -p … couchbase/server:enterprise port mapping, because host port 11210 is held by another container on this machine. The same image and steps were exercised through container networking instead.
• The host.docker.internal note for the Dockerized app.

CI: see checks on this PR (Node JS Tests runs against the repo's Capella vars and isn't affected by a README-only change).

Risk

Docs only. The credentials are labeled as local-development-only.

🤖 Generated with Claude Code