Skip to content

docs: add verified getting-started workflow - #13

Merged
jemsbhai merged 1 commit into
mainfrom
codex/getting-started
Aug 15, 2026
Merged

docs: add verified getting-started workflow#13
jemsbhai merged 1 commit into
mainfrom
codex/getting-started

Conversation

@jemsbhai

Copy link
Copy Markdown
Owner

Summary

  • add a Docker-first getting-started guide with clone, startup, first-use, lifecycle, troubleshooting, source-development, and production-boundary instructions
  • add a checked-in Next.js development environment template and surface the quick start near the top of the README
  • harden the documented Compose path with a writable Next.js cache tmpfs and bounded MinIO initialization retries
  • add documentation, configuration, and deployment contract coverage so the copy-paste workflow cannot drift silently

Why

CorpusKit had all required Dockerfiles and locked dependency manifests, but startup guidance was scattered and the native-development sequence was not runnable as written. A fresh empty-volume smoke also exposed a transient MinIO DNS race, and the root environment example contained blank typed settings that could not be loaded directly.

User impact

A new user now needs only Git and a running Docker Engine with Compose v2 for the local demo. Host Python, Node.js, npm, and eSpeak are not required. The guide clearly labels the demo identity as local-only and documents persistence, safe shutdown, destructive reset, port overrides, and the separate production path.

No requirements.txt was added: pyproject.toml + uv.lock remain the authoritative Python requirements, and package.json + package-lock.json remain authoritative for the web app.

Validation

  • fresh isolated Compose builds and empty-volume --profile web up --build --detach --wait
  • API readiness, authenticated demo session, real corpus creation, and browser rendering with no console errors
  • docker compose --profile web config --quiet
  • docker compose --profile '*' config --quiet
  • 184 focused documentation/deployment/release/config tests passed
  • 188 broader deployment/release/config tests passed, 56 opt-in tests skipped
  • Ruff format/check, mypy (133 source files), Prettier, uv lock --check, and git diff --check passed

@jemsbhai
jemsbhai marked this pull request as ready for review August 15, 2026 21:14
@jemsbhai
jemsbhai merged commit 2ce883b into main Aug 15, 2026
15 checks passed
@jemsbhai
jemsbhai deleted the codex/getting-started branch August 15, 2026 21:37
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