fix(docs): add working ingest:example script, correct quickstart#1137
Merged
Conversation
The README and quickstart referenced `npm run ingest:example` (which did not exist) and stated that `docker compose up` starts the API — it only starts OpenSearch and LocalStack, so `curl localhost:3000` failed (#1084). - Add `examples/sample-collection.json` + `examples/sample-item.json` and a `bin/ingest-example.mjs` script (wired to `npm run ingest:example`) that posts them to the local API via the Transaction extension. It gives a clear hint if the API isn't running and retries the item create while the new collection becomes searchable. - Correct the README quick start and quickstart Step 1 to `npm install` + `npm run serve` (the API), and clarify what `docker compose` actually starts. Closes #1084. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR fixes the “sample ingest” and “quickstart” documentation flow by adding a working npm run ingest:example script and updating the docs to accurately reflect that docker compose starts dependencies (OpenSearch/LocalStack) while npm run serve runs the STAC API locally.
Changes:
- Adds
bin/ingest-example.mjsand wires it up asnpm run ingest:exampleto ingest sample collection/item via Transactions. - Updates README + getting-started quickstart to include
npm install, run the API withnpm run serve, and clarify what Compose does/doesn’t start. - Adds example STAC JSON payloads used by the ingest script and manual quickstart steps.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates quickstart commands to include install + npm run serve and then ingest/query. |
| package.json | Adds ingest:example script (and should also ensure eslint covers .mjs). |
| examples/sample-collection.json | Adds ready-made sample collection used by docs + ingest script. |
| examples/sample-item.json | Adds ready-made sample item used by docs + ingest script. |
| docs/getting-started/quickstart.md | Fixes Step 1 to start dependencies with Compose and run API via npm run serve; adds an ingest tip. |
| bin/ingest-example.mjs | New CLI script to post the example collection/item to a local API with retries and re-run tolerance. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "build-api-docs": "npx @redocly/cli build-docs src/lambdas/api/openapi.yaml -o ./docs/api-spec.html", | ||
| "prepare": "husky" | ||
| "prepare": "husky", | ||
| "ingest:example": "node bin/ingest-example.mjs" |
Comment on lines
+29
to
+31
| `docker compose` starts OpenSearch and LocalStack; `npm run serve` runs the STAC API | ||
| on `http://localhost:3000` with the Transaction extension enabled (so the steps below | ||
| can create collections and items). |
Per review: - Rename bin/ingest-example.mjs -> .js so it's covered by `npm run lint` (the repo is ESM, and the eslint script only globs .js/.ts). - Correct the quickstart "Transaction extension errors" section, which still toggled transactions via `docker compose` even though the API now runs via `npm run serve`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
jkeifer
approved these changes
Jul 1, 2026
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.
Summary
Fixes #1084 — the documented sample-data flow didn't work:
npm run ingest:example, which didn't exist.docker compose upstarts the API on :3000 — it only starts OpenSearch + LocalStack, socurl localhost:3000connection-refused.Changes
bin/ingest-example.mjs+npm run ingest:example— postsexamples/sample-collection.jsonandexamples/sample-item.jsonto the local API via the Transaction extension. HonorsSTAC_API_URL(defaulthttp://localhost:3000), prints a clear hint if the API isn't reachable, tolerates 409 (re-runnable), and retries the item create while the new collection becomes searchable (OpenSearch's ~1s refresh).npm install+npm run serve, and clarify thatdocker composestarts OpenSearch/LocalStack whilenpm run serveruns the API.Verification
Ran locally end-to-end:
docker compose up -d→npm run serve→npm run ingest:example→curl '/search?collections=sample-collection'returnssample-item.Closes #1084
🤖 Generated with Claude Code