overture-stack · MitchellShiell · Jul 8, 2025 · Jul 24, 2026 · Jul 27, 2026 · Jul 28, 2026
diff --git a/Makefile b/Makefile
@@ -4,14 +4,20 @@
 DEMO_MODE := 0
 FORCE := 0
 
+# Repository root. Defined before the tool detection below, which depends on it.
+ROOT_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
+
 # Required System files
-DOCKER_COMPOSE_EXE := $(shell which docker-compose)
+# Prefer the Compose V2 plugin ("docker compose"), falling back to the standalone
+# V1 binary. V1 is no longer shipped with current Docker Desktop releases.
+DOCKER_COMPOSE_EXE := $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || which docker-compose)
 CURL_EXE := $(shell which curl)
-MVN_EXE := $(shell which mvn)
+# Prefer the Maven wrapper bundled with this repository, so a system-wide Maven
+# install is not required.
+MVN_EXE := $(shell if [ -x $(ROOT_DIR)/mvnw ]; then echo $(ROOT_DIR)/mvnw; else which mvn; fi)
 
 # Variables
 DOCKERFILE_NAME := $(shell if [ $(DEMO_MODE) -eq 1 ]; then echo Dockerfile; else echo Dockerfile.dev; fi)
-ROOT_DIR := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
 MY_UID := $$(id -u)
 MY_GID := $$(id -g)
 THIS_USER := $(MY_UID):$(MY_GID)

diff --git a/README.md b/README.md
@@ -17,9 +17,9 @@ Song functions as a file catalog system, tracking files and managing their metad
 
 Technical resources for those working with or contributing to the project are available from our official documentation site, the following content can also be read and updated within the `/docs` folder of this repository.
 
-- **[Song Overview](https://docs.overture.bio/docs/core-software/Song/overview)** 
-- [**Setting up the Development Enviornment**](https://docs.overture.bio/docs/core-software/Song/setup)
-- [**Common Usage Docs**](https://docs.overture.bio/docs/core-software/Song/setup)
+- **[Song Overview](https://docs.overture.bio/develop/Song/overview)** 
+- [**Setting up the Development Enviornment**](https://docs.overture.bio/develop/Song/setup)
+- [**Common Usage Docs**](https://docs.overture.bio/develop/Song/setup)
 
 ##  Development Environment
 
@@ -32,7 +32,7 @@ Technical resources for those working with or contributing to the project are av
 
 - For support, feature requests, and bug reports, please see our [Support Guide](https://docs.overture.bio/community/support).
 
-- For detailed information on how to contribute to this project, please see our [Contributing Guide](https://docs.overture.bio/docs/contribution).
+- For detailed information on how to contribute to this project, please see our [Contributing Guide](https://docs.overture.bio/develop/contributing).
 
 ## Related Software 
 
@@ -50,7 +50,7 @@ The Overture Platform includes the following Overture Components:
 |[Lyric](https://github.com/overture-stack/lyric)| A model-agnostic, tabular data submission system |
 |[Lectern](https://github.com/overture-stack/lectern)| Schema Manager, designed to validate, store, and manage collections of data dictionaries.  |
 
-If you'd like to get started using our platform [check out our quickstart guides](https://docs.overture.bio/guides/getting-started)
+If you'd like to get started using our platform [check out our quickstart guides](https://docs.overture.bio/deploy)
 
 ## Funding Acknowledgement
 

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,7 +1,9 @@
 version: "3.7"
 services:
   keycloak-server:
-    image: docker.io/bitnami/keycloak:22
+    # Bitnami moved its versioned Docker Hub tags to the bitnamilegacy archive in 2025;
+    # docker.io/bitnami/keycloak:22 no longer resolves. See DEVELOPMENT notes before bumping.
+    image: docker.io/bitnamilegacy/keycloak:22
     environment:
       - KC_DB=postgres
       - KC_DB_URL=jdbc:postgresql://keycloak-postgresql/bitnami_keycloak
@@ -23,7 +25,7 @@ services:
         curl -sL https://github.com/oicr-softeng/keycloak-apikeys/releases/download/1.0.1/keycloak-apikeys-1.0.1.jar -o /opt/bitnami/keycloak/providers/keycloak-apikeys-1.0.1.jar
         kc.sh start-dev --import-realm
   keycloak-postgresql:
-    image: docker.io/bitnami/postgresql:11
+    image: docker.io/bitnamilegacy/postgresql:11
     environment:
       # ALLOW_EMPTY_PASSWORD is recommended only for development.
       - ALLOW_EMPTY_PASSWORD=yes

diff --git a/docs/00-overview.md b/docs/00-overview.md
@@ -31,7 +31,7 @@ As part of the larger Overture.bio software suite, Song is typically used with a
 .
 ├── /song-client
 ├── /song-core
-└── /song-servers
+└── /song-server
 ```
 
 [Click here to view the Song respository on GitHub ](https://github.com/overture-stack/song)
@@ -62,7 +62,6 @@ These packages are:
 - **song-docker-demo**: Example all-in-one deployment of Song with Score with other external project Auth and ID services.
 - **song-docs**: Deprecated `readthedocs` documentation site
 - **song-go-client**: Alternate cli imlementation, written in GoLang.
-- **song-java-sdk**: Code library for java applications to interact with a Song server programatically.
-- **song-python-sdk**: Code library for java applications to interact with a Song server programatically.
+- **song-python-sdk**: Code library for Python applications to interact with a Song server programatically.
 
 
diff --git a/docs/01-setup.md b/docs/01-setup.md
@@ -13,55 +13,59 @@ This guide will walk you through setting up a complete development environment,
 
 ### Setting up supporting services
 
-We'll use our Quickstart service, a flexible Docker Compose setup, to spin up Song's complementary services.
+The Song repository ships its own `docker-compose.yml` and `Makefile`, which together start every service Song depends on. No other repository is required.
 
-1. Clone the Quickstart repository and move into its directory:
+1. Clone Song and move into its directory:
 
    ```bash
-   git clone -b quickstart https://github.com/overture-stack/prelude.git
-   cd prelude
+   git clone https://github.com/overture-stack/song.git
+   cd song
    ```
 
-2. Run the appropriate start command for your operating system:
+2. Start Song's dependencies:
 
-   | Operating System | Command              |
-   | ---------------- | -------------------- |
-   | Unix/macOS       | `make SongDev`       |
-   | Windows          | `./make.bat SongDev` |
+   ```bash
+   make start-deps
+   ```
 
     <details>
     <summary>**Click here for a detailed breakdown**</summary>
 
-   This command will set up all complementary services for Song development as follows:
-
-   ![SongDev](./assets/songDev.svg "Song Dev Environment")
+   `make start-deps` packages the project and then brings up Keycloak, Score, and object storage from the repository's `docker-compose.yml`:
 
    | Service     | Port   | Description                                     | Purpose in Song Development                            |
    | ----------- | ------ | ----------------------------------------------- | ------------------------------------------------------ |
-   | Conductor   | `9204` | Orchestrates deployments and environment setups | Manages the overall development environment            |
-   | Keycloak-db | -      | Database for Keycloak (no exposed port)         | Stores Keycloak data for authentication                |
-   | Keycloak    | `8180` | Authorization and authentication service        | Provides OAuth2 authentication for Score               |
-   | Song-db     | `5433` | Database for Song                               | Stores metadata managed by Song                        |
+   | Keycloak    | `9082` | Authorization and authentication service        | Provides OAuth2 authentication for Song                |
+   | Keycloak-db | `9444` | Database for Keycloak                           | Stores Keycloak data for authentication                |
    | Score       | `8087` | File Transfer service                           | Handles file uploads, downloads, and storage operation |
-   | Minio       | `9000` | Object storage provider                         | Simulates S3-compatible storage for Score              |
+   | Minio       | `8085` | Object storage provider                         | Simulates S3-compatible storage for Score              |
+
+   Keycloak starts with the `myrealm` realm imported from `docker/keycloak-init/data_import`, and downloads the `keycloak-apikeys` provider on start-up so it can issue API keys.
+
+   To bring up Song itself along with its database and all of the above, use `make start-song-server` instead. That adds:
+
+   | Service     | Port           | Description           | Purpose in Song Development      |
+   | ----------- | -------------- | --------------------- | -------------------------------- |
+   | Song-db     | `8432`         | Database for Song     | Stores metadata managed by Song  |
+   | Song-server | `8080`, `5006` | The Song server       | The service under development; `5006` is the JVM debug port |
 
    - Ensure these ports are free on your system before starting the environment.
    - You may need to adjust the ports in the `docker-compose.yml` file if you have conflicts with existing services.
+   - `make clean` tears the stack down and removes the build output; `make log-song-server` tails the server's logs.
+
+   :::note
 
-   For more information, see our [Quickstart documentation linked here](https://docs.overture.bio/docs/other-software/Quickstart)
+   These targets build the project with the bundled Maven wrapper and drive Docker Compose, so a JDK is required even when you only want the supporting services. See the prerequisites above.
+
+   :::
 
     </details>
 
 ### Running the Development Server
 
-1.  Clone Song and move into its directory:
-
-    ```bash
-    git clone https://github.com/overture-stack/song.git
-    cd song
-    ```
+Use these steps to run Song on your host, against the supporting services started above. To run Song in a container instead, `make start-song-server` covers both.
 
-2.  Build the application locally:
+1.  Build the application locally:
 
     ```bash
     ./mvnw clean install -DskipTests
@@ -88,15 +92,15 @@ We'll use our Quickstart service, a flexible Docker Compose setup, to spin up So
 
     :::
 
-3.  Start the Song Server:
+2.  Start the Song Server:
 
     ```bash
     ./mvnw spring-boot:run -Dspring-boot.run.profiles=default,dev,secure -pl song-server
     ```
 
         :::info
 
-             If you are looking to configure Song for your specific environment, [**the Song-server configuration file can be found here**](https://github.com/overture-stack/score/blob/develop/score-server/src/main/resources/application.yml). A summary of the available Spring profiles is provided below:
+             If you are looking to configure Song for your specific environment, [**the Song-server configuration file can be found here**](https://github.com/overture-stack/song/blob/develop/song-server/src/main/resources/application.yml). A summary of the available Spring profiles is provided below:
 
              <details>
              <summary>**Click here for a summary of the Song-server spring profiles**</summary>
@@ -143,21 +147,24 @@ After installing and configuring Song, verify that the system is functioning cor
      - Verify you're using the correct URL
 
 3. **Test GET Analysis Endpoint**
+
+   This step needs a study to query. The repository's Compose stack starts with an empty database, so create one first (see [Data model management](/develop/Song/Reference/data-model-management)) and substitute its ID for `<your-study-id>` below.
+
    - Using Swagger UI:
      1. Locate the `GetAnalysesForStudy` endpoint in the **Analysis** section: `GET /studies/{studyId}/analysis/paginated`
      2. Click to expand and select "Try it out"
      3. Set parameters:
         - analysisStates: PUBLISHED
-        - studyId: demo
+        - studyId: `<your-study-id>`
      4. Click "Execute"
    - Alternatively, use curl:
      ```bash
-     curl -X GET "http://localhost:8080/studies/demo/analysis?analysisStates=PUBLISHED" -H "accept: */*"
+     curl -X GET "http://localhost:8080/studies/<your-study-id>/analysis?analysisStates=PUBLISHED" -H "accept: */*"
      ```
-   - Expected result: JSON response containing analysis data for the demo study
+   - Expected result: JSON response containing the analyses registered under that study
 
 :::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=).
 :::
 
 ## Song-Client Setup
@@ -166,19 +173,67 @@ The `song-client` is a CLI tool used for communicating with a `song-server`. For
 
 ```bash
 docker run -d --name song-client \
-   -e CLIENT_ACCESS_TOKEN=68fb42b4-f1ed-4e8c-beab-3724b99fe528 \
-   -e CLIENT_STUDY_ID=demo \
+   -e CLIENT_ACCESS_TOKEN=<your-api-key> \
+   -e CLIENT_STUDY_ID=<your-study-id> \
    -e CLIENT_SERVER_URL=http://localhost:8080 \
    --network="host" \
    --platform="linux/amd64" \
    --mount type=bind,source=${pwd},target=/output \
 ghcr.io/overture-stack/song-client:5.1.1 \
 ```
 
+:::info Obtaining an API key
+
+`CLIENT_ACCESS_TOKEN` is environment-specific; there is no fixed development token. The Keycloak that `make start-deps` brings up on port `9082` loads the `keycloak-apikeys` provider, which issues keys against the `myrealm` realm. See [Authentication](/develop/Song/Reference/authentication) for how the provider is installed and how Song validates the keys it issues.
+
+<details>
+<summary>**Click here for the steps to generate a key against the local stack**</summary>
+
+The realm ships the users `admin` (a member of the `ADMIN` group) and `testca_user` (a member of `TESTCASONG_GROUP`), both with hashed passwords that are not recoverable from the realm export. Keys can only be issued by their owner or an administrator, so start by giving one of those users a password you know.
+
+1. Open the Keycloak admin console at `http://localhost:9082` and sign in. The image's default administrator credentials are `user` / `bitnami`.
+
+2. In the `myrealm` realm, set a password for the `admin` user (**Users** → `admin` → **Credentials**). Note its user ID from the same page; you will need it below.
+
+3. Request a token for that user. The realm's `system` client has direct access grants enabled:
+
+   ```bash
+   curl -X POST "http://localhost:9082/realms/myrealm/protocol/openid-connect/token" \
+     -d "grant_type=password" \
+     -d "client_id=system" -d "client_secret=systemsecret" \
+     -d "username=admin" -d "password=<the password you just set>"
+   ```
+
+4. Exchange that token for an API key, substituting the user ID from step 2:
+
+   ```bash
+   curl -X POST "http://localhost:9082/realms/myrealm/apikey/api_key?user_id=<user-id>&scopes=song.WRITE&scopes=score.WRITE" \
+     -H "Authorization: Bearer <access_token from step 3>"
+   ```
+
+   The `name` field of the response is the key value. Pass it as `CLIENT_ACCESS_TOKEN`:
+
+   ```json
+   {
+     "name": "5b1da354-37bd-409d-b938-ea14b8035bc3",
+     "scope": ["score.WRITE", "song.WRITE"],
+     "expiryDate": "2027-07-30T15:32:59.990+0000",
+     "isRevoked": false
+   }
+   ```
+
+Scopes take the form `<resource>.<READ|WRITE>`, and the resources the realm defines are `song`, `score`, `TEST-CA`, and `ABC123`. A request for a scope the user's group does not carry is rejected with `Invalid Scope`.
+
+</details>
+
+`CLIENT_STUDY_ID` must name a study that already exists on your server. The repository's Compose stack starts with an empty database, so create one first; see [Data model management](/develop/Song/Reference/data-model-management).
+
+:::
+
     <details>
     <summary>**Click here for an explaination of command above**</summary>
-      - `-e CLIENT_ACCESS_TOKEN=68fb42b4-f1ed-4e8c-beab-3724b99fe528` sets up the song-client with a pre-configured system-wide access token that works with the conductor service setup.
-      - `-e CLIENT_STUDY_ID=demo` the quickstart is pre-configured with a Study ID named demo, we supply the Study ID value to the song-client on start-up.
+      - `-e CLIENT_ACCESS_TOKEN=<your-api-key>` supplies the API key the song-client authenticates with, obtained from Keycloak as described above.
+      - `-e CLIENT_STUDY_ID=<your-study-id>` the Study ID the song-client operates against, supplied on start-up.
       - `-e CLIENT_SERVER_URL=http://localhost:8080` is the url for the Song server which the Song-Client will interact with.
       - `--network="host"` Uses the host network stack inside the container, bypassing the usual network isolation. This means the container shares the network namespace with the host machine.
       - `--platform="linux/amd64"` Specifies the platform the container should emulate. In this case, it's set to linux/amd64, indicating the container is intended to run on a Linux system with an AMD64 architecture.

diff --git a/docs/02-Usage/00-submitting-metadata.md → docs/02-Reference/00-submitting-metadata.md b/docs/02-Usage/00-submitting-metadata.md → docs/02-Reference/00-submitting-metadata.md
@@ -1,9 +1,9 @@
 # Metadata Submission
 
-Submitting new metadata entries ([Analyses](https://docs.overture.bio/docs/core-software/Song/Usage/#song-terminology)) to Song.
+Submitting new metadata entries ([Analyses](/develop/Song/Reference/#song-terminology)) to Song.
 
 :::info CLI Submission Guide
-This page documents the basic submission flow, for a more detailed guide see our [**platform guide on CLI submissions**](https://docs.overture.bio/guides/user-guides/cli-submissions).
+This page documents the basic submission flow, for a more detailed guide see our [**platform guide on CLI submissions**](/use/cli-submissions).
 :::
 
 ### Client Installation
@@ -80,7 +80,7 @@ This page documents the basic submission flow, for a more detailed guide see our
 
 ### Step 1: Prepare a Payload
 
-Create a metadata payload conforming to a registered `analysis_type` schema. For more information, see our section covering [Data Model Management](https://docs.overture.bio/docs/core-software/Song/Usage/data-model-management).
+Create a metadata payload conforming to a registered `analysis_type` schema. For more information, see our section covering [Data Model Management](/develop/Song/Reference/data-model-management).
 
 ### Step 2: Upload the Metadata Payload
 
@@ -138,7 +138,7 @@ Set the analysis state to `PUBLISHED`:
 docker exec song-client sh -c "sing publish -a a4142a01-1274-45b4-942a-01127465b422"
 ```
 
-For more information, see our documentation on [**Song publication controls**](https://docs.overture.bio/docs/core-software/Song/Usage/publication-controls)
+For more information, see our documentation on [**Song publication controls**](/develop/Song/Reference/publication-controls)
 
 :::info Search & Exploration
 For optimal data querying, use Song with our search & exploration services Maestro, Arranger and Stage. With these components you can index and query and explore Song data through an intuitive search portal.
@@ -149,5 +149,5 @@ For optimal data querying, use Song with our search & exploration services Maest
 - If you encounter connection or internal server errors, have your admin verify that the Song and Score servers are correctly configured.
 
 :::info Support
-For technical support, please don't hesitate to reach out through our relevant [**community support channels**](https://docs.overture.bio/community/support).
+For technical support, 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=).
 :::