Using Overture

For those interacting with, and managing Overture platforms and services.

Each guide and tutorial below pairs with a locally deployable Overture demo environment. Feel free to use these pages purely as reference, the demos are optional.

Who these guides are for

These guides are grouped by role in the sidebar. If you are not sure where to start, find yourself below.

Data Consumers

Researchers and analysts who search and retrieve data from a platform someone else runs.

• Ask a portal questions in plain language. AI-Assisted Data Discovery covers the researcher workflow, a locally deployable testing environment, and reproducible use cases you can adapt to your own portal.
• Connect the client you already use. Any MCP-compatible host (LM Studio, Claude Desktop, and others) can be pointed at a portal's Arranger MCP server using the provided configuration templates.
• Download the files you find. File Download walks through retrieving data from a platform with the Song and Score command-line clients.

Data Submitters

Anyone contributing data files and their accompanying metadata to a platform.

• Complete a full submission workflow. File Submission takes you through registering an analysis with Song and uploading its files with Score.
• Understand what a submission is. A submission pairs data files (BAMs, CRAMs, VCFs, and similar) with the metadata that gives them context, including donor information and file descriptions.
• See what your submission is validated against. The permitted fields, types, and values are set by the platform's administrators; Building Song Schemas explains the schemas your metadata is checked against.

Platform Administrators

Those deploying, configuring, and maintaining an Overture platform.

• Stand up a portal end to end. Building a Foundational Search Portal deploys Elasticsearch, Arranger, and Stage over your own tabular CSV data.
• Configure each piece in depth. Separate guides cover Lectern dictionaries, Song schemas, search facets and data tables, and index mappings.
• Generate configs instead of writing them. The generators and playgrounds turn a CSV into a full set of starter configuration files, or let you shape a dictionary or schema by hand. All of them run entirely in your browser.

Prerequisites

Most demo environments use Docker Compose with similar setups. Before starting you can install and verify the following:

0. WSL2 Setup (windows only)

Docker Desktop on Windows runs on WSL2, so configure it before installing Docker Desktop below:

1. Install WSL2
2. Use Ubuntu or another Linux distribution within WSL2
3. Enable Docker Desktop's WSL2 integration (Docker Desktop → Settings → Resources → WSL Integration)
4. Run all commands from a Bash terminal inside WSL2, not PowerShell or Command Prompt. To open one, search for your Linux distribution (e.g. "Ubuntu") in the Start menu.

1. Git installed

Download from git-scm.com if the command is not recognised.

2. Docker Desktop (28.0.0 or later)

• macOS / Windows: Download from docker.com/products/docker-desktop
• Linux: Follow the Docker Engine install guide

Once installed, open Docker Desktop → Settings → Resources and set:

• CPUs: 4+ cores (8 recommended)
• Memory: 8 GB minimum
• Disk: 10 GB+ available

Please ensure docker --version and docker compose version both return version numbers, and Docker Desktop is running with 4+ CPUs and 8 GB+ memory allocated

Help us make our guides better

If you can't find what you're looking for please don't hesitate to reach out through our support page or our discussion forum.