From 4f04a29c92e4ae2974e58038562766d4824a41ae Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Mon, 27 Jul 2026 15:24:53 -0400 Subject: [PATCH 01/11] usage > reference --- docs/{usage => reference}/01-upload.md | 2 +- docs/{usage => reference}/02-download.md | 0 docs/{usage => reference}/03-object-storage.md | 0 docs/{usage => reference}/04-authentication.md | 0 docs/{usage => reference}/05-hashicorp-vault.md | 0 docs/{usage => reference}/06-api-reference.mdx | 2 +- docs/{usage => reference}/07-client-reference.md | 2 +- docs/{usage/usage.mdx => reference/reference.mdx} | 6 ++---- docs/setup.md | 2 +- 9 files changed, 6 insertions(+), 8 deletions(-) rename docs/{usage => reference}/01-upload.md (95%) rename docs/{usage => reference}/02-download.md (100%) rename docs/{usage => reference}/03-object-storage.md (100%) rename docs/{usage => reference}/04-authentication.md (100%) rename docs/{usage => reference}/05-hashicorp-vault.md (100%) rename docs/{usage => reference}/06-api-reference.mdx (89%) rename docs/{usage => reference}/07-client-reference.md (96%) rename docs/{usage/usage.mdx => reference/reference.mdx} (87%) diff --git a/docs/usage/01-upload.md b/docs/reference/01-upload.md similarity index 95% rename from docs/usage/01-upload.md rename to docs/reference/01-upload.md index 00613b3a..515c33fe 100644 --- a/docs/usage/01-upload.md +++ b/docs/reference/01-upload.md @@ -89,5 +89,5 @@ Upload completed ``` :::info Support -If you encounter any issues or have questions, 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, 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=). ::: diff --git a/docs/usage/02-download.md b/docs/reference/02-download.md similarity index 100% rename from docs/usage/02-download.md rename to docs/reference/02-download.md diff --git a/docs/usage/03-object-storage.md b/docs/reference/03-object-storage.md similarity index 100% rename from docs/usage/03-object-storage.md rename to docs/reference/03-object-storage.md diff --git a/docs/usage/04-authentication.md b/docs/reference/04-authentication.md similarity index 100% rename from docs/usage/04-authentication.md rename to docs/reference/04-authentication.md diff --git a/docs/usage/05-hashicorp-vault.md b/docs/reference/05-hashicorp-vault.md similarity index 100% rename from docs/usage/05-hashicorp-vault.md rename to docs/reference/05-hashicorp-vault.md diff --git a/docs/usage/06-api-reference.mdx b/docs/reference/06-api-reference.mdx similarity index 89% rename from docs/usage/06-api-reference.mdx rename to docs/reference/06-api-reference.mdx index 085011d4..6a9482ad 100644 --- a/docs/usage/06-api-reference.mdx +++ b/docs/reference/06-api-reference.mdx @@ -35,4 +35,4 @@ import SwaggerAPIDoc from '/src/components/SwaggerAPIDoc'; ### 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) \ No newline at end of file +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=). \ No newline at end of file diff --git a/docs/usage/07-client-reference.md b/docs/reference/07-client-reference.md similarity index 96% rename from docs/usage/07-client-reference.md rename to docs/reference/07-client-reference.md index 33c8c7ea..fe2e78fc 100644 --- a/docs/usage/07-client-reference.md +++ b/docs/reference/07-client-reference.md @@ -132,4 +132,4 @@ Additional option flags available for the `score-client` executable: ## Need Help? -If you encounter any issues or have questions, please don't hesitate to reach out through our relevant [community support channels](https://docs.overture.bio/community/support) \ No newline at end of file +If you encounter any issues or have questions, 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=). \ No newline at end of file diff --git a/docs/usage/usage.mdx b/docs/reference/reference.mdx similarity index 87% rename from docs/usage/usage.mdx rename to docs/reference/reference.mdx index 09bee5d4..16dc7145 100644 --- a/docs/usage/usage.mdx +++ b/docs/reference/reference.mdx @@ -1,8 +1,6 @@ -# Usage +# Reference - - -The following usage docs provide instructions for common tasks and workflows in Score: +The following reference docs provide instructions for common tasks and workflows in Score:

diff --git a/docs/setup.md b/docs/setup.md index 3b3c0f71..632878f3 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -141,7 +141,7 @@ After installing and configuring Score, verify that the system is functioning co - Verify you're using the correct URL :::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=). ::: ## Score-Client Setup From ebc44c5f25dbfe839b207cae25132fd8d8a0cc76 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Tue, 28 Jul 2026 16:02:17 -0400 Subject: [PATCH 02/11] docs update --- docs/reference/01-upload.md | 3 +-- docs/reference/02-download.md | 4 ++-- docs/reference/03-object-storage.md | 4 ++-- docs/reference/04-authentication.md | 26 +++++++++++++------------- docs/reference/05-hashicorp-vault.md | 2 +- docs/reference/06-api-reference.mdx | 6 +++--- docs/reference/07-client-reference.md | 4 +--- docs/setup.md | 2 +- 8 files changed, 24 insertions(+), 27 deletions(-) diff --git a/docs/reference/01-upload.md b/docs/reference/01-upload.md index 515c33fe..6efea2ba 100644 --- a/docs/reference/01-upload.md +++ b/docs/reference/01-upload.md @@ -3,7 +3,7 @@ Data uploads using the Client or API. :::info Data Submission Guide -For detailed step-by-step instructions on using Song and Score clients for data submissions, see our [**platform guide on CLI submissions**](https://docs.overture.bio/guides/user-guides/cli-submissions). +For detailed step-by-step instructions on using Song and Score clients for data submissions, see our [**platform guide on CLI submissions**](/use/cli-submissions). ::: ## Installing Score-Client @@ -56,7 +56,6 @@ Use the Score Client's `upload` command to upload file data. Main upload methods | --------------------- | ---------------------------------------------- | | `--force` | Re-upload existing files (overwrite) | | `--md5` | Specify MD5 checksum of the file | -| `--validate` | Validate file using MD5 checksum | | `--verify-connection` | Verify object storage connection before upload | ### Upload Example diff --git a/docs/reference/02-download.md b/docs/reference/02-download.md index 09e3b8fa..8a6bd00f 100644 --- a/docs/reference/02-download.md +++ b/docs/reference/02-download.md @@ -3,7 +3,7 @@ Data download using the Score Client. :::info Download Guide -For detailed step-by-step instructions on using Song and Score clients for data downloads, see our [**platform guide on CLI downloads**](https://docs.overture.bio/guides/user-guides/cli-downloads). +For detailed step-by-step instructions on using Song and Score clients for data downloads, see our [**platform guide on CLI downloads**](/use/cli-downloads). ::: ## Installing Score-Client @@ -77,5 +77,5 @@ docker exec score-client sh -c "score-client download --manifest ./` with your desired download location :::info Score Client Reference Doc -For more information see our [**Score Client command reference documentation**](https://docs.overture.bio/docs/core-software/Score/usage/client-reference) +For more information see our [**Score Client command reference documentation**](/develop/Score/reference/client-reference) ::: diff --git a/docs/reference/03-object-storage.md b/docs/reference/03-object-storage.md index 84c756c4..86592982 100644 --- a/docs/reference/03-object-storage.md +++ b/docs/reference/03-object-storage.md @@ -45,10 +45,10 @@ To connect Score with AWS, Ceph, or Minio storage, modify your `.env.score` file # Object Storage Configuration Variables # ============================ -SPRING_PROFILES_ACTIVE=prod,aws +SPRING_PROFILES_ACTIVE=prod,s3 S3_ENDPOINT=http://localhost:9000 -S3_ACCESS_KEY=minio +S3_ACCESSKEY=minio S3_SECRETKEY=minio123 S3_SIGV4ENABLED=true diff --git a/docs/reference/04-authentication.md b/docs/reference/04-authentication.md index 7127038d..a07b8d72 100644 --- a/docs/reference/04-authentication.md +++ b/docs/reference/04-authentication.md @@ -183,13 +183,12 @@ AUTH_SERVER_URL=http://localhost:8080/realms/{realmName}/apikey/check_api_key/ AUTH_SERVER_TOKENNAME=apiKey AUTH_SERVER_CLIENTID=score-api AUTH_SERVER_CLIENTSECRET=scoresecret -AUTH_SERVER_SCOPE_STUDY_PREFIX=score. -AUTH_SERVER_SCOPE_UPLOAD_SUFFIX=.WRITE -AUTH_SERVER_SCOPE_DOWNLOAD_SUFFIX=.READ -AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM=score.WRITE -AUTH_SERVER_SCOPE_DOWNLOAD_SUFFIX=.READ -AUTH_SERVER_SCOPE_UPLOAD_SYSTEM=score.READ -AUTH_SERVER_SCOPE_UPLOAD_SUFFIX=.WRITE +AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_PREFIX=PROGRAMDATA- +AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_SUFFIX=.READ +AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM=score.READ +AUTH_SERVER_SCOPE_UPLOAD_STUDY_PREFIX=PROGRAMDATA- +AUTH_SERVER_SCOPE_UPLOAD_STUDY_SUFFIX=.WRITE +AUTH_SERVER_SCOPE_UPLOAD_SYSTEM=score.WRITE SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWKSETURI=http://localhost:8080/realms/{realm-name}/protocol/openid-connect/certs ``` @@ -199,7 +198,7 @@ Replace any default values with the values specific to your environment. The var **Click here for details** **Profile Configuration** -- `SPRING_PROFILES_ACTIVE`: Defines active Spring profiles for the application (aws,prod,secure) +- `SPRING_PROFILES_ACTIVE`: Defines active Spring profiles for the application (s3,prod,secure) **Server and Authentication Settings** - `SERVER_PORT`: The port number on which the server will listen (default: 8087) @@ -220,11 +219,12 @@ Replace any default values with the values specific to your environment. The var - `AUTH_SERVER_CLIENTSECRET`: Client secret found under "Client details" → "Credentials tab" **Scope Configuration** -- `AUTH_SERVER_SCOPE_STUDY_PREFIX`: Prefix for study-specific scopes (default: score.) -- `AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM`: System-level download scope (default: score.WRITE) -- `AUTH_SERVER_SCOPE_DOWNLOAD_SUFFIX`: Study-level download scope suffix (default: .READ) -- `AUTH_SERVER_SCOPE_UPLOAD_SYSTEM`: System-level upload scope (default: score.READ) -- `AUTH_SERVER_SCOPE_UPLOAD_SUFFIX`: Study-level upload scope suffix (default: .WRITE) +- `AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_PREFIX`: Prefix for study-level download scopes (default: PROGRAMDATA-) +- `AUTH_SERVER_SCOPE_DOWNLOAD_STUDY_SUFFIX`: Suffix for study-level download scopes (default: .READ) +- `AUTH_SERVER_SCOPE_DOWNLOAD_SYSTEM`: System-level download scope (default: score.READ) +- `AUTH_SERVER_SCOPE_UPLOAD_STUDY_PREFIX`: Prefix for study-level upload scopes (default: PROGRAMDATA-) +- `AUTH_SERVER_SCOPE_UPLOAD_STUDY_SUFFIX`: Suffix for study-level upload scopes (default: .WRITE) +- `AUTH_SERVER_SCOPE_UPLOAD_SYSTEM`: System-level upload scope (default: score.WRITE) **JWT Configuration** - `SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWKSETURI`: URI for JWT JSON Web Key Set for OAuth2 resource server diff --git a/docs/reference/05-hashicorp-vault.md b/docs/reference/05-hashicorp-vault.md index ce22c7cd..221aebf8 100644 --- a/docs/reference/05-hashicorp-vault.md +++ b/docs/reference/05-hashicorp-vault.md @@ -100,7 +100,7 @@ There are two authentication methods with Vault: - `role-id`: A permanent identifier (like a username) - `secret-id`: A rotatable credential (like a password) - AppRole provides enhanced security features like credential rotation, fine-grained access control, and IP restrictions. Contact your Vault administrator to set up AppRole authentication. xwFor details, see [Vault's AppRole documentation](https://developer.hashicorp.com/vault/docs/auth/approle). + AppRole provides enhanced security features like credential rotation, fine-grained access control, and IP restrictions. Contact your Vault administrator to set up AppRole authentication. For details, see [Vault's AppRole documentation](https://developer.hashicorp.com/vault/docs/auth/approle). ::: :::warning Security Notice diff --git a/docs/reference/06-api-reference.mdx b/docs/reference/06-api-reference.mdx index 6a9482ad..e0b100f5 100644 --- a/docs/reference/06-api-reference.mdx +++ b/docs/reference/06-api-reference.mdx @@ -6,12 +6,12 @@ Scores API is a RESTful API that uses JSON for request and response bodies. It f Depending on your environment, the Scores Swagger API can be accessed from the following URLs: -- Development URL: `http://localhost:8087/swagger.html` +- Development URL: `http://localhost:8087/swagger-ui.html` - Example production URL: `https://score.demo.overture.bio/swagger-ui.html` ### Authentication -In production environments, all requests to the Songs API require authentication using an API key. +In production environments, all requests to the Score API require authentication using an API key. Include your API key in the `Authorization` header of each request as follows: @@ -20,7 +20,7 @@ Authorization: Bearer YOUR_API_KEY ``` :::info API Key Access & Management -For information on accessing an API key from a deployed Overture platform, [**see our platform guide here**](https://docs.overture.bio/guides/user-guides/cli-submissions#generate-an-api-key). +For information on accessing an API key from a deployed Overture platform, [**see our platform guide here**](/use/cli-submissions). For information on generating and managing API keys in Overture using Keycloak, [**see our administration guide on identity & access management here**](https://docs.overture.bio/guides/administration-guides). ::: diff --git a/docs/reference/07-client-reference.md b/docs/reference/07-client-reference.md index fe2e78fc..db6cd9e2 100644 --- a/docs/reference/07-client-reference.md +++ b/docs/reference/07-client-reference.md @@ -77,7 +77,6 @@ Commands and options supported by the Score client. | `--manifest` | Upload files using manifest file ID, URL, or path | | `--md5` | MD5 checksum of file to upload | | `--object-id` | Upload specific file by object ID | - | `--validate` | Perform MD5 checksum validation if available | | `--verify-connection` | Verify connection to object storage repository first | ## Url @@ -109,12 +108,11 @@ Commands and options supported by the Score client. | `--input-file-index` | Local path to index file (requires --input-file) | | `--manifest` | Manifest file for querying object IDs and ranges | | `--object-id` | Specific object ID to download slice from | - | `--output-file` | Name of output file | | `--output-format` | Output file format (SAM or BAM) | | `--output-dir` | Path to output directory (with --manifest) | | `--output-index` | Write index files to output (with --manifest) | | `--output-original-header` | Output entire original header | - | `--output-type` | Structure of output file (CROSS, MERGED, or TRIMMED) | + | `--output-type` | Structure of output file (only `TRIMMED` is implemented) | | `--query` | Query for BAM file content extraction (coordinate format) | | `--reference-file` | Local path to FASTA file for CRAM decoding | | `--stdout` | Send output to stdout (forces SAM format) | diff --git a/docs/setup.md b/docs/setup.md index 632878f3..1ac8cdd9 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -48,7 +48,7 @@ We'll use our quickstart service, a flexible Docker Compose setup, to spin up Sc - 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. - For more information, see our [quickstart documentation linked here](https://docs.overture.bio/docs/other-software/quickstart) + For more information, see our [quickstart documentation linked here](/deploy/quickstart) From c334b50e4254ebe808d9166bec8cf457ea40fcbf Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Thu, 30 Jul 2026 11:08:38 -0400 Subject: [PATCH 03/11] docs: repoint stale docs.overture.bio links at current paths 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. --- README.md | 10 +++++----- docs/reference/06-api-reference.mdx | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4967d101..95e376f1 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,9 @@ Score is a file transfer service designed to enable large-file upload and downlo 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. -- **[Score Overview](https://docs.overture.bio/docs/core-software/Score/overview)** -- [**Setting up the Development Environment**](https://docs.overture.bio/docs/core-software/Score/setup) -- [**Common Usage Docs**](https://docs.overture.bio/docs/core-software/Score/setup) +- **[Score Overview](https://docs.overture.bio/develop/Score/overview)** +- [**Setting up the Development Environment**](https://docs.overture.bio/develop/Score/setup) +- [**Common Usage Docs**](https://docs.overture.bio/develop/Score/setup) ## Development Environment @@ -43,7 +43,7 @@ Technical resources for those working with or contributing to the project are av ## Support & Contributions - 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 @@ -61,7 +61,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/docs/reference/06-api-reference.mdx b/docs/reference/06-api-reference.mdx index e0b100f5..ab8f96e9 100644 --- a/docs/reference/06-api-reference.mdx +++ b/docs/reference/06-api-reference.mdx @@ -22,7 +22,7 @@ Authorization: Bearer YOUR_API_KEY :::info API Key Access & Management For information on accessing an API key from a deployed Overture platform, [**see our platform guide here**](/use/cli-submissions). -For information on generating and managing API keys in Overture using Keycloak, [**see our administration guide on identity & access management here**](https://docs.overture.bio/guides/administration-guides). +For information on generating and managing API keys in Overture using Keycloak, [**see our administration guide on identity & access management here**](https://docs.overture.bio/use). ::: ### Endpoints From f38fe5d208169d0c812a557223fb51b5aeafac7f Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Thu, 30 Jul 2026 11:15:51 -0400 Subject: [PATCH 04/11] setup page update --- Makefile | 12 ++++++--- docs/setup.md | 74 +++++++++++++++++++++++++++++---------------------- 2 files changed, 51 insertions(+), 35 deletions(-) diff --git a/Makefile b/Makefile index 4e11286d..c4403e97 100644 --- 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 := $$(id -u):$$(id -g) diff --git a/docs/setup.md b/docs/setup.md index 1ac8cdd9..0851864d 100644 --- a/docs/setup.md +++ b/docs/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 Score's complementary services. +The Score repository ships its own `docker-compose.yml` and `Makefile`, which together start every service Score depends on. No other repository is required. -1. Clone the quickstart repository and move into its directory: +1. Clone Score 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/score.git + cd score ``` -2. Run the appropriate start command for your operating system: +2. Start Score's dependencies: - | Operating System | Command | - | ---------------- | --------------------- | - | Unix/macOS | `make scoreDev` | - | Windows | `./make.bat scoreDev` | + ```bash + make start-deps + ```
**Click here for a detailed breakdown** - This command will set up all complementary services for Score development as follows: + `make start-deps` packages the project and then brings up Keycloak, Song, and object storage from the repository's `docker-compose.yml`: + + | Service | Port | Description | Purpose in Score Development | + | ----------- | ------- | ----------------------------------------------- | ------------------------------------------- | + | Keycloak | `9082` | Authorization and authentication service | Provides OAuth2 authentication for Score | + | Keycloak-db | `9444` | Database for Keycloak | Stores Keycloak data for authentication | + | Song | `8080` | Metadata management service | Manages metadata for files stored by Score | + | Song-db | `12345` | Database for Song | Stores metadata managed by Song | + | 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. The Song server is a pinned prebuilt image rather than a local build. - ![ScoreDev](./assets/scoreDev.svg "Score Dev Environment") + To bring up Score itself along with all of the above, use `make start-score-server` instead. That adds: - | Service | Port | Description | Purpose in Score 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 | - | Song | `8080` | Metadata management service | Manages metadata for files stored by Score | - | Minio | `9000` | Object storage provider | Simulates S3-compatible storage for Score | + | Service | Port | Description | Purpose in Score Development | + | ------------ | -------------- | ---------------- | ------------------------------------------------------------ | + | Score-server | `8087`, `5006` | The Score 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-score-server` tails the server's logs. - For more information, see our [quickstart documentation linked here](/deploy/quickstart) + :::note + + 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. + + :::
### Running the Development Server -1. Clone Score and move into its directory: +Use these steps to run Score on your host, against the supporting services started above. To run Score in a container instead, `make start-score-server` covers both. - ```bash - git clone https://github.com/overture-stack/score.git - cd score - ``` - -2. Build the application locally: +1. Build the application locally: ```bash ./mvnw clean install -DskipTests @@ -88,7 +92,7 @@ We'll use our quickstart service, a flexible Docker Compose setup, to spin up Sc ::: -3. Start the Score Server: +2. Start the Score Server: ```bash ./mvnw spring-boot:run -Dspring-boot.run.profiles=default,s3,secure,dev -pl score-server @@ -150,7 +154,7 @@ The `score-client` is a CLI tool used for communicating with a `score-server`. F ```bash docker run -d --name score-client \ - -e ACCESSTOKEN=68fb42b4-f1ed-4e8c-beab-3724b99fe528 \ + -e ACCESSTOKEN= \ -e STORAGE_URL=http://localhost:8087 \ -e METADATA_URL=http://localhost:8080 \ --network="host" \ @@ -159,11 +163,17 @@ docker run -d --name score-client \ ghcr.io/overture-stack/score-client:latest ``` +:::info Obtaining an API key + +`ACCESSTOKEN` 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. Generate a key there and pass its value here. See [Authentication](/develop/Score/reference/authentication) for how the provider is installed and how Score validates the keys it issues. + +::: +
**Click here for an explaination of command above** - - `-e ACCESSTOKEN=68fb42b4-f1ed-4e8c-beab-3724b99fe528` sets up the score-client with a pre-configured system-wide access token that works with the quickstart service setup. - - `-e STORAGE_URL=http://score:8087` is the url for the Score server that the Score-Client will interact with. - - `-e METADATA_URL=http://song:8080` is the url for the song server that the score-client will interact with. + - `-e ACCESSTOKEN=` supplies the API key the score-client authenticates with, obtained from Keycloak as described above. + - `-e STORAGE_URL=http://localhost:8087` is the url for the Score server that the Score-Client will interact with. + - `-e METADATA_URL=http://localhost:8080` is the url for the song server that the score-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. - `--mount type=bind,source={pwd},target=/output` mounts the directory and its contents (volume) from the host machine to the container. In this case, it binds the present working directory from the host to /output inside the container. Any changes made to the files in this directory will be reflected in both locations. From d4f98d09c93b82b2d797e2c4b6007dd29d71d9b7 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Thu, 30 Jul 2026 11:47:35 -0400 Subject: [PATCH 05/11] updated dev quickstart, retiring prelude on all components --- docker-compose.yml | 6 ++++-- docs/setup.md | 42 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 45 insertions(+), 3 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 73ee5b5b..94c11bc4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,8 @@ 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 @@ -22,7 +24,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/setup.md b/docs/setup.md index 0851864d..14e0c5e6 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -165,7 +165,47 @@ docker run -d --name score-client \ :::info Obtaining an API key -`ACCESSTOKEN` 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. Generate a key there and pass its value here. See [Authentication](/develop/Score/reference/authentication) for how the provider is installed and how Score validates the keys it issues. +`ACCESSTOKEN` 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/Score/reference/authentication) for how the provider is installed and how Score validates the keys it issues. + +
+**Click here for the steps to generate a key against the local stack** + +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=" + ``` + +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=&scopes=score.WRITE&scopes=score.READ" \ + -H "Authorization: Bearer " + ``` + + The `name` field of the response is the key value. Pass it as `ACCESSTOKEN`: + + ```json + { + "name": "5b1da354-37bd-409d-b938-ea14b8035bc3", + "scope": ["score.READ", "score.WRITE"], + "expiryDate": "2027-07-30T15:32:59.990+0000", + "isRevoked": false + } + ``` + +Scopes take the form `.`, 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`. + +
::: From c53237547c5a782cf4e825edf3bb1e21159c5ee9 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Tue, 4 Aug 2026 09:57:37 -0400 Subject: [PATCH 06/11] docs: use full docs.overture.bio URLs for content outside this repo 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. --- docs/reference/01-upload.md | 4 ++-- docs/reference/02-download.md | 2 +- docs/reference/06-api-reference.mdx | 2 +- docs/reference/07-client-reference.md | 2 +- docs/setup.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/reference/01-upload.md b/docs/reference/01-upload.md index 6efea2ba..e4ac9328 100644 --- a/docs/reference/01-upload.md +++ b/docs/reference/01-upload.md @@ -3,7 +3,7 @@ Data uploads using the Client or API. :::info Data Submission Guide -For detailed step-by-step instructions on using Song and Score clients for data submissions, see our [**platform guide on CLI submissions**](/use/cli-submissions). +For detailed step-by-step instructions on using Song and Score clients for data submissions, see our [**platform guide on CLI submissions**](https://docs.overture.bio/use/cli-submissions). ::: ## Installing Score-Client @@ -88,5 +88,5 @@ Upload completed ``` :::info Support -If you encounter any issues or have questions, 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=). +If you encounter any issues or have questions, please don't hesitate to reach out through our [**support page**](https://docs.overture.bio/community/support) or our [**discussion forum**](https://github.com/overture-stack/docs/discussions?discussions_q=). ::: diff --git a/docs/reference/02-download.md b/docs/reference/02-download.md index 8a6bd00f..31b3ba4e 100644 --- a/docs/reference/02-download.md +++ b/docs/reference/02-download.md @@ -3,7 +3,7 @@ Data download using the Score Client. :::info Download Guide -For detailed step-by-step instructions on using Song and Score clients for data downloads, see our [**platform guide on CLI downloads**](/use/cli-downloads). +For detailed step-by-step instructions on using Song and Score clients for data downloads, see our [**platform guide on CLI downloads**](https://docs.overture.bio/use/cli-downloads). ::: ## Installing Score-Client diff --git a/docs/reference/06-api-reference.mdx b/docs/reference/06-api-reference.mdx index ab8f96e9..9e6d1082 100644 --- a/docs/reference/06-api-reference.mdx +++ b/docs/reference/06-api-reference.mdx @@ -35,4 +35,4 @@ import SwaggerAPIDoc from '/src/components/SwaggerAPIDoc'; ### Need Help? -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=). \ No newline at end of file +If you encounter any issues or have questions about our API, please don't hesitate to reach out through our [**support page**](https://docs.overture.bio/community/support) or our [**discussion forum**](https://github.com/overture-stack/docs/discussions?discussions_q=). \ No newline at end of file diff --git a/docs/reference/07-client-reference.md b/docs/reference/07-client-reference.md index db6cd9e2..53b65242 100644 --- a/docs/reference/07-client-reference.md +++ b/docs/reference/07-client-reference.md @@ -130,4 +130,4 @@ Additional option flags available for the `score-client` executable: ## Need Help? -If you encounter any issues or have questions, 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=). \ No newline at end of file +If you encounter any issues or have questions, please don't hesitate to reach out through our [**support page**](https://docs.overture.bio/community/support) or our [**discussion forum**](https://github.com/overture-stack/docs/discussions?discussions_q=). \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index 14e0c5e6..4c58247e 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -145,7 +145,7 @@ After installing and configuring Score, verify that the system is functioning co - Verify you're using the correct URL :::info Need Help? -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=). +If you encounter any issues or have questions about our API, please don't hesitate to reach out through our [**support page**](https://docs.overture.bio/community/support) or our [**discussion forum**](https://github.com/overture-stack/docs/discussions?discussions_q=). ::: ## Score-Client Setup From 8fed4584c58e3feba675cb1bea8bfe4187afc473 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Tue, 4 Aug 2026 09:57:51 -0400 Subject: [PATCH 07/11] docs: link to this repo's own pages with relative paths 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. --- docs/reference/02-download.md | 2 +- docs/setup.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/02-download.md b/docs/reference/02-download.md index 31b3ba4e..a270859c 100644 --- a/docs/reference/02-download.md +++ b/docs/reference/02-download.md @@ -77,5 +77,5 @@ docker exec score-client sh -c "score-client download --manifest ./` with your desired download location :::info Score Client Reference Doc -For more information see our [**Score Client command reference documentation**](/develop/Score/reference/client-reference) +For more information see our [**Score Client command reference documentation**](./07-client-reference.md) ::: diff --git a/docs/setup.md b/docs/setup.md index 4c58247e..beb2e271 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -165,7 +165,7 @@ docker run -d --name score-client \ :::info Obtaining an API key -`ACCESSTOKEN` 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/Score/reference/authentication) for how the provider is installed and how Score validates the keys it issues. +`ACCESSTOKEN` 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](./reference/04-authentication.md) for how the provider is installed and how Score validates the keys it issues.
**Click here for the steps to generate a key against the local stack** From 1ca96d04291bcfaeab56ba449a41ba4f7166c5c7 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Tue, 4 Aug 2026 09:58:09 -0400 Subject: [PATCH 08/11] docs: retarget the API key links, whose targets lacked the promised content 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. --- docs/reference/06-api-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/06-api-reference.mdx b/docs/reference/06-api-reference.mdx index 9e6d1082..fa1364d0 100644 --- a/docs/reference/06-api-reference.mdx +++ b/docs/reference/06-api-reference.mdx @@ -20,9 +20,9 @@ Authorization: Bearer YOUR_API_KEY ``` :::info API Key Access & Management -For information on accessing an API key from a deployed Overture platform, [**see our platform guide here**](/use/cli-submissions). +For information on setting up the API key provider on a deployed Overture platform, [**see our Keycloak deployment guide**](https://docs.overture.bio/deploy/deployment/keycloak). -For information on generating and managing API keys in Overture using Keycloak, [**see our administration guide on identity & access management here**](https://docs.overture.bio/use). +For information on generating and managing API keys in Overture using Keycloak, [**see our Keycloak configuration reference**](./04-authentication.md). ::: ### Endpoints From 3818b1d4014ad5c3528a6eaf91afaa716bdf7a56 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Tue, 4 Aug 2026 10:08:47 -0400 Subject: [PATCH 09/11] fix duplicated docs link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 95e376f1..a2f60d92 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Technical resources for those working with or contributing to the project are av - **[Score Overview](https://docs.overture.bio/develop/Score/overview)** - [**Setting up the Development Environment**](https://docs.overture.bio/develop/Score/setup) -- [**Common Usage Docs**](https://docs.overture.bio/develop/Score/setup) +- [**Reference Docs**](https://docs.overture.bio/develop/Score/reference) ## Development Environment From 70df89bfa39f9becb5de5fc1e8f8c509347b6cd8 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Wed, 5 Aug 2026 14:04:40 -0400 Subject: [PATCH 10/11] removed quickstart references from readme --- README.md | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index a2f60d92..f1434550 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,11 @@ Score is a file transfer service designed to enable large-file upload and downlo
-> >
> >
-> -> *Score is part of [Overture](https://www.overture.bio/), a collection of open-source software microservices used to create platforms for researchers to organize and share genomics data.* -> +> +> _Score is part of [Overture](https://www.overture.bio/), a collection of open-source software microservices used to create platforms for researchers to organize and share genomics data._ ## Key Features @@ -29,11 +27,11 @@ Score is a file transfer service designed to enable large-file upload and downlo 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. -- **[Score Overview](https://docs.overture.bio/develop/Score/overview)** +- **[Score Overview](https://docs.overture.bio/develop/Score/overview)** - [**Setting up the Development Environment**](https://docs.overture.bio/develop/Score/setup) - [**Reference Docs**](https://docs.overture.bio/develop/Score/reference) -## Development Environment +## Development Environment - [Java 11 (OpenJDK)](https://openjdk.java.net/projects/jdk/11/) - [Maven 3.5+](https://maven.apache.org/) (or use provided wrapper) @@ -45,27 +43,26 @@ 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/develop/contributing). -## Related Software +## Related Software The Overture Platform includes the following Overture Components:
-|Software|Description| -|---|---| -|[Score](https://github.com/overture-stack/score/)| Transfer data to and from any cloud-based storage system | -|[Song](https://github.com/overture-stack/song/)| Catalog and manage metadata associated to file data spread across cloud storage systems | -|[Maestro](https://github.com/overture-stack/maestro/)| Organizing your distributed data into a centralized Elasticsearch index | -|[Arranger](https://github.com/overture-stack/arranger/)| A search API with reusable search UI components | -|[Stage](https://github.com/overture-stack/stage)| A React-based web portal scaffolding | -|[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/deploy) +| Software | Description | +| ------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| [Score](https://github.com/overture-stack/score/) | Transfer data to and from any cloud-based storage system | +| [Song](https://github.com/overture-stack/song/) | Catalog and manage metadata associated to file data spread across cloud storage systems | +| [Maestro](https://github.com/overture-stack/maestro/) | Organizing your distributed data into a centralized Elasticsearch index | +| [Arranger](https://github.com/overture-stack/arranger/) | A search API with reusable search UI components | +| [Stage](https://github.com/overture-stack/stage) | A React-based web portal scaffolding | +| [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. | ## Funding Acknowledgement Overture is supported by grant #U24CA253529 from the National Cancer Institute at the US National Institutes of Health, and additional funding from Genome Canada, the Canada Foundation for Innovation, the Canadian Institutes of Health Research, Canarie, and the Ontario Institute for Cancer Research. #### Powered by + [![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSourceSupport) From 2f51f7dc028fe9620140f142a737f8110d4d1d76 Mon Sep 17 00:00:00 2001 From: Mitchell Shiell Date: Wed, 5 Aug 2026 14:06:48 -0400 Subject: [PATCH 11/11] contributing link updated to in repo ref --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f1434550..2d53692c 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Technical resources for those working with or contributing to the project are av ## Support & Contributions - 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/develop/contributing). +- For detailed information on how to contribute to this project, please see our [Contributing Guide](./CONTRIBUTING.md). ## Related Software