Overture docs update by MitchellShiell · Pull Request #257 · overture-stack/stage

MitchellShiell · 2026-07-30T13:21:08Z

Documentation for the Overture docs site.

The setup guide told readers to clone the Prelude docs-demo/search-portal-workshop branch to get a back end to develop against. Prelude is being retired as the source of component dev environments, so Stage now ships its own, a new dev-services/ directory, and docs/setup.md is rewritten around it.

Nothing under components/, pages/ or global/ is touched. The only source addition is dev-services/.

`dev-services/` (new)

Stage is front-end scaffolding: its table, facets and query bar are Arranger UI components, so they render nothing without an Arranger search API behind them, and Arranger needs a search engine in turn. This supplies both, so no second repository is required.

File	Contents
`docker-compose.yml`	OpenSearch (`9200`), a one-shot `setup` container, Arranger search server (`5050`)
`Makefile`	`up`, `down`, `status`, `logs`, `reset`
`configs/opensearch/donor-mapping.json`	Index template for `donor-index` and its `donor_centric` alias
`configs/arranger/donor/`	Arranger catalogue: `base`, `extended`, `facets`, `table`, `matchbox`
`data/donor.ndjson`	373 mock ARGO clinical donor documents in `_bulk` form
`README.md`	Orientation for anyone opening the directory directly

Worth a reviewer's attention:

Stage is deliberately not in the stack. You run it on your host with npm run dev, so the copy you edit is the copy you see. The old Prelude demo brought up its own Stage on 3000, which is why readers were told to develop on 3001, to avoid colliding with a portal they were not editing.
OpenSearch runs with its security plugin disabled, hence no credentials; both the README and the guide say not to use this anywhere network-exposed. Both ports bind to 127.0.0.1 only.
make up is idempotent and waits. The setup container applies the template, creates the index and alias, bulk-loads, then exits; later starts skip finished work. --wait plus Arranger's healthcheck means it does not return until Arranger is serving the catalogue.
make reset is the only destructive target and prompts for a typed DELETE.
Provenance: documents and configs come from the Prelude docs-demo/ai-assisted-data-discovery demo, so a portal built here lines up with that one.
Image pins: opensearchproject/opensearch:2.17.1 and ghcr.io/overture-stack/arranger-search-server:b5c6051b, overridable via OPENSEARCH_TAG / ARRANGER_TAG. The Arranger pin is an unreleased commit build, so it wants bumping to a release tag once one is cut with the catalogue behaviour these configs rely on.

`docs/setup.md`

The clone step is now Stage itself, followed by cd dev-services && make up.
The service table is replaced. The old one listed Elasticsearch, Arranger, Postgres and a Stage container from the demo, with credentials elastic / myelasticpassword. None of it applies now.
NEXT_PUBLIC_ARRANGER_INDEX corrected from datatable1-index to donor-index, and each variable now cites dev-services/configs/arranger/donor/base.json as the file that sets it.
Adds a GraphQL verification step with the expected result ({"data":{"records":{"hits":{"total":373}}}}), so the back end can be confirmed before touching Stage.
Explains why NEXT_PUBLIC_ARRANGER_API_URL needs no catalogue path: Arranger mounts a single registered catalogue at the root, switching to /<catalogue>/graphql only once there is more than one.
The 3001 recommendation stays but its reason is corrected: it is just about leaving 3000 free.

`README.md`

Stale docs/core-software/Stage/* links → /develop/Stage/*, contributing → /develop/contributing, getting started → /deploy.

Before merging

dev-services/ and docs/setup.md have to land together; the guide walks through a directory that does not exist on main.
Confirm the pinned ARRANGER_TAG is acceptable, or swap it for a release tag.

justincorrigible · 2026-07-30T15:00:21Z


 :::info Need Help?
-If you encounter any issues or have questions about our API, please don't hesitate to reach out through our relevant [**community support channels**](https://docs.overture.bio/community/support).
+If you encounter any issues or have questions about our API, please don't hesitate to reach out through our [**support page**](/community/support) or our [**discussion forum**](https://github.com/overture-stack/docs/discussions?discussions_q=).


same issue here. the full url being replaced was the right approach

/community/support is still there

justincorrigible · 2026-07-30T15:57:11Z

+- [**Stage Overview**](https://docs.overture.bio/develop/Stage/overview)
+- [**Setting up the Development Environment**](https://docs.overture.bio/develop/Stage/setup)


are these capital S in stage required by docusaurus? I'd try to avoid making urls case sensitive whenever possible. odds are these links are fine with lowercase

i believe docusaurus, it renders the name in the sidebar based on the folder name

to confirm, that means you named the folder with capitals?

The site renamed /docs/core-software/* to /build/* to /develop/*, moved /docs/contribution to /develop/contributing, /guides/getting-started to /deploy, and /guides/administration-guides to /use. Each old path only resolved through a redirect hop. Verified every new target against a local site build.

justincorrigible · 2026-07-30T22:02:34Z

+  # one (donor) and NEXT_PUBLIC_ARRANGER_API_URL is just http://localhost:5050.           #
+  # ---------------------------------------------------------------------------------- #
+  arranger:
+    image: ghcr.io/overture-stack/arranger-search-server:${ARRANGER_TAG:-b5c6051b}


the fallback should be a release version, never a commit ref tag. will provide 3.1.0 soon, we're just finishing some touches, so marking this as pending in my local Stage's debt doc (which I will push soon after we merge this PR)

no actionable here for you now

justincorrigible · 2026-07-30T22:16:29Z

nice work overall, @MitchellShiell! this is a real improvement over the Prelude dependency: self-contained, idempotent, and in particular I like that the security posture is handled properly (localhost-only binding, security plugin explicitly called out as dev-only in three places, no real credentials in the compose file).

A couple of smaller notes:

dropping Keycloak from the doc is nice. one fewer thing to explain away as "just a placeholder."
fair point on Docusaurus deriving the sidebar name from the folder, but I'd still lean toward lowercase URLs where possible to avoid case-sensitivity surprises later. Not blocking, your call whether to change it now or leave a note for later.
will continue reviewing, but now from the Arranger perspective, as the configs seem to be based on an outdated version of the server

MitchellShiell mentioned this pull request Jul 30, 2026

Overture docs V2 update overture-stack/docs#48

Open

5 tasks

MitchellShiell requested a review from justincorrigible July 30, 2026 14:25

justincorrigible reviewed Jul 30, 2026

View reviewed changes

Comment thread docs/setup.md Outdated

justincorrigible reviewed Jul 30, 2026

View reviewed changes

MitchellShiell requested a review from justincorrigible July 30, 2026 15:50

justincorrigible reviewed Jul 30, 2026

View reviewed changes

MitchellShiell added 5 commits July 30, 2026 13:40

usage > reference

43b82bb

docs update

d821942

setup page update

43efea2

updated dev quickstart, retiring prelude on all components

607490f

MitchellShiell force-pushed the overtureDocsUpdate branch from bbc361f to 607490f Compare July 30, 2026 17:40

justincorrigible reviewed Jul 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Overture docs update - #257

Overture docs update#257
MitchellShiell wants to merge 5 commits into
mainfrom
overtureDocsUpdate

MitchellShiell commented Jul 30, 2026 •

edited

Loading

Uh oh!

Uh oh!

justincorrigible Jul 30, 2026

Uh oh!

justincorrigible Jul 30, 2026

Uh oh!

justincorrigible Jul 30, 2026

Uh oh!

MitchellShiell Jul 30, 2026

Uh oh!

justincorrigible Jul 30, 2026

Uh oh!

justincorrigible Jul 30, 2026

Uh oh!

justincorrigible commented Jul 30, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		- [Stage Overview](https://docs.overture.bio/develop/Stage/overview)
		- [Setting up the Development Environment](https://docs.overture.bio/develop/Stage/setup)

Uh oh!

Conversation

MitchellShiell commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

dev-services/ (new)

docs/setup.md

README.md

Before merging

Uh oh!

Uh oh!

justincorrigible Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

justincorrigible Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

justincorrigible Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

MitchellShiell Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

justincorrigible Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

justincorrigible Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

justincorrigible commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MitchellShiell commented Jul 30, 2026 •

edited

Loading

`dev-services/` (new)

`docs/setup.md`

`README.md`

justincorrigible commented Jul 30, 2026 •

edited

Loading