Overture docs update - #504
Open
MitchellShiell wants to merge 9 commits into
Open
Conversation
5 tasks
MitchellShiell
force-pushed
the
overtureDocsUpdate
branch
from
July 30, 2026 16:04
8709f74 to
40f4dc0
Compare
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.
MitchellShiell
force-pushed
the
overtureDocsUpdate
branch
from
July 30, 2026 17:39
40f4dc0 to
d4f98d0
Compare
Bare site paths (/community/support, /use/cli-submissions, /use/cli-downloads) only resolve once these files are assembled into the docs site. Read directly on GitHub, in a clone, or in an IDE they 404. Links pointing at content outside this repository now use the full URL form, matching the README. Six links across five files. The remaining /use/cli-submissions link, in 06-api-reference.mdx, is left for a follow-up commit: its target does not hold the content the link promises, so it needs retargeting rather than rewriting.
Two links to Score's own pages were written as absolute site paths. Relative paths resolve both standalone and through the aggregated site; the absolute form only works in the latter. setup.md points down into reference/, and 02-download.md points at a sibling.
…ontent
The API Key Access & Management admonition carried two links that did not lead
to what they described. Same defect as Song's api-reference page, fixed the
same way.
- "accessing an API key from a deployed Overture platform" pointed at
/use/cli-submissions, a bare site path whose page has no API key content at
all. Now points at the Keycloak deployment guide, which is where the
Overture API Key Provider is actually installed on a deployment.
- "administration guide on identity & access management" pointed at the
generic /use overview. No such administration guide exists. The content it
describes, generating and managing API keys through Keycloak, is this repo's
own Configuring Keycloak page, so it now points there relatively.
Both link texts updated to name what the reader will find. This also clears the
last bare site path in the repo.
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
1 participant
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.
Documentation for the Overture docs site.
Two things:
docs/usage/→docs/reference/to match the other components, and the setup guide rewritten around this repo's own Compose stack instead of the retired Preludequickstartbranch.Source changes are limited to
Makefileanddocker-compose.yml: dev tooling, no application logic, no Java.Setup guide
The old guide opened with
git clone -b quickstart .../prelude.git. That branch is retired, so it now uses thedocker-compose.ymlandMakefilealready in this repo.make start-deps→ Keycloak9082, keycloak-db9444, Song8080, song-db12345, Minio8085.make start-score-serveradds score-server8087(debug5006).8180,9000,5433), not ours. Corrected, and the Conductor row is gone, because there is no Conductor here.adminpassword in Keycloak, get a token via thesystemclient's direct access grant, exchange it atapikey/api_keyfor ascore.READ/score.WRITEkey. Replaces the hardcodedACCESSTOKEN, a Quickstart value that worked nowhere else.myrealmand downloadskeycloak-apikeysat start-up; the targets build with./mvnw, so a JDK is needed even for the supporting services alone.make cleanandmake log-score-serverdocumented.Source changes
Makefile. The guide does not work without these:docker compose version, falls back to the standalone binary. V1 no longer ships with Docker Desktop, so every Compose target failed outright on a current install.MVN_EXEprefers the bundled./mvnwover a systemmvn.ROOT_DIRmoves above the detection block that now depends on it.docker-compose.yml. Without this the stack could not pull at all.bitnami/keycloak:22andbitnami/postgresql:11→bitnamilegacy/*; Bitnami archived its versioned tags in 2025. Commented in place.docs/usage/→docs/reference/All eight pages move with content intact;
usage.mdxbecomesreference.mdx.Corrections in
reference/04-authentication.mdThe example env block did not match the server's config keys: wrong names,
DOWNLOAD_SUFFIXlisted twice, andDOWNLOAD_SYSTEM/UPLOAD_SYSTEMtransposed. Now:SPRING_PROFILES_ACTIVEsaidaws,prod,secure; for this configuration it iss3,prod,secure.README.mdStale
docs/core-software/Score/*links →/develop/Score/*, contributing →/develop/contributing, getting started →/deploy.