docs: first-10-minutes README + troubleshooting catalogue - #443
Merged
Conversation
Signed-off-by: Mohamed Tayeb Mokni <tayeb.mokni@gmail.com>
Replace the stale, duplicated quickstart with a single linear path that reflects what we actually learned running the stack: make up is the canonical entry point, gonext init shipped (issue #425), the /setup wizard shipped (issue #426), the admin proxies through Next.js rewrites, NEXT_PUBLIC_API_URL="" is the deliberate empty-string signal for that proxy, and the docker-compose.override.yml pattern is how you dodge port conflicts. Add a documentation-map table pointing at docs/00, docs/17, docs/18, and the new docs/20-troubleshooting.md. Finalize license messaging (core FSL-1.1-Apache-2.0, SDK Apache-2.0 — no longer 'being finalized'). Signed-off-by: Mohamed Tayeb Mokni <tayeb.mokni@gmail.com>
…oting
docs/18-local-development.md:
- Add 'The docker-compose.override.yml pattern' section with the
Postgres-on-5433 example and other common overrides.
- Add 'How the admin reaches the API' section explaining the
Next.js rewrite, why NEXT_PUBLIC_API_URL="" is the deliberate
signal, and how the build-arg bakes the destination.
- Extend the troubleshooting section with the symptoms that bit us
during M11: pepper mismatch, useSearchParams Suspense boundary,
stale .next cache after switching between Compose and pnpm dev.
docs/20-troubleshooting.md (new): catalogues the same failures plus a
broader set across stack-won't-start / first-run bootstrap /
admin app / workers / clean reset / diagnostics. Linked from the
README and from docs/18.
Signed-off-by: Mohamed Tayeb Mokni <tayeb.mokni@gmail.com>
Tables in the new README sections and docs/20-troubleshooting.md were mixing 'aligned' and 'compact' table-column-style — markdownlint's default profile flags that as MD060 inconsistency. Normalize to the compact style used by ADRs and most newer docs in the repo. Also tightens the host-port table in docs/18-local-development.md so the minio row's pipes line up with the rest. No content changes. Signed-off-by: Mohamed Tayeb Mokni <tayeb.mokni@gmail.com>
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
2 participants
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.
Summary
The README and local-dev docs were stale: they referenced
gonext initas "scaffolded but not yet shipped" (it shipped in #425), missed the/setupwizard (#426), and didn't reflect the lessons from actually running the stack — port conflicts, the override-file pattern, whyNEXT_PUBLIC_API_URL=""is deliberate, why the build needs aGONEXT_API_URLbuild-arg, pepper alignment, theuseSearchParamsSuspense gotcha.Rewrites:
README.md— single linear quickstart (clone → cp .env → make up → init OR /setup → /login), screenshot reference for the new branded login, "Local development tips" with the override pattern + proxy reasoning, "What's where" table, documentation map pointing at docs/00, /17, /18, /20, finalized license messaging (FSL-1.1-Apache-2.0 core / Apache-2.0 SDK).docs/18-local-development.md— adds "The docker-compose.override.yml pattern" section and "How the admin reaches the API: Next.js rewrites, not CORS" section. Extends troubleshooting with pepper mismatch, Suspense boundary, stale.next/cache.docs/20-troubleshooting.md(new) — symptom → cause → fix catalogue across stack-won't-start, first-run bootstrap, admin app, workers, clean reset, diagnostics. Linked from the README and docs/18.Markdown lint is clean on all three files (the pre-existing MD060/MD034 violations on lines 12, 36–75 of docs/18 are out of scope and untouched).
Test plan
cp .env.example .env && make upthengonext initor/setupwizard, sign in at/login.docker-compose.override.ymlwithpostgres: ports: ["5433:5432"], confirmmake upsucceeds with a native Postgres also running.apps/admin/public/logo-wordmark.svgexists (it does — file shipped in feat(admin): brand foundation — tokens, fonts, shadcn primitives, <Headline>, restyled /login #432); follow-up captures the actual screenshot atdocs/design/screenshots/login.png.Closes the README staleness raised in M11. Screenshot capture is intentionally deferred — note in the README.
🤖 Generated with Claude Code