cBioPortal: the v7 move to a ClickHouse-only backend splits the deployment story

What the portal does and which repository holds it

cBioPortal for Cancer Genomics provides visualisation, analysis and download of large-scale cancer genomics data sets. The user is a cancer researcher or clinician who wants to look at mutations, copy number and clinical outcomes for a cohort without writing their own data warehouse, and the person who deploys it is an institution running a private instance of the portal.

The repository split matters more here than in most projects, and the README says so directly. This repository contains only the backend part. The user interface lives in a separate frontend repository, and the README points developers who only want to make frontend changes at that repository and its own instructions.

For that reason the README also sends you to the architecture overview documentation before editing anything, since cBioPortal consists of several components and you need to know which repository a given change belongs in. Before touching backend code, it points at the backend code organisation document, and for anyone working on new features it gives a contact address and a Slack channel rather than leaving coordination to chance.

The build is Maven, with a `pom.xml` at the root, and the tree shows the usual supporting material: `docker/`, `dev/`, `docs/`, `scripts/`, `src/`, `test/`, a `bom.json` for dependency management, a `version.sh`, and configuration for CircleCI and Code Climate. There is also an `OPEN-SOURCE-DOCUMENTATION` directory and a `SECURITY.md`, plus an `AGENTS.md` that suggests the project has been set up for automated contribution tooling.

master is a pre-release branch, and the v6 line is frozen except for security

The branching and release strategy is the single most consequential piece of documentation in this README, and it is easy to skim past.

The `master` branch is now the pre-release branch for v7, and pull requests targeting v7 should be opened against `master`. For deployments that are still on v6, the project has created a `maintenance-v6` branch, and the rules for it are stated without ambiguity. Only important security fixes will be merged into `maintenance-v6`. No new bug fixes or feature development will be done on v6. Users still running v6 are told to continue tracking `maintenance-v6` for security updates.

That is a clean statement of a two-tier support model, and it has direct consequences. A v6 instance gets security patches and nothing else, which means a functional defect you hit on v6 will not be fixed on that branch. If your deployment depends on a v6 feature, staying on v6 is a decision to freeze your own feature set too.

The published releases show how fast this is moving. v7.2.0 was tagged on 2026-10-15, v7.1.3 on 2026-10-13 and v7.1.2 on 2026-09-17, and the last push to `master` was on 2026-10-15. The repository is not archived.

Note the tension between the README wording and the tag list. The README describes the project as currently preparing for v7 and `master` as the pre-release branch, yet v7 point releases are already being cut. The practical reading is that v7 is pre-release in the sense that it is the branch where v7 work lands, not in the sense that it is unreleased. The details are in `docs/Versioning-and-Upgrades.md`, which the README links, and that document is the one to read before choosing a branch.

ClickHouse-only is a compatibility break, not a config option

v7 introduces a ClickHouse-only database setup, and the README states plainly that this new database setup is not compatible with earlier portal settings, the traditional MySQL mode, or existing study importer tools.

That is the sentence to slow down on. It rules out three separate things at once, and the third is the one that catches institutions out. A portal is only as useful as the studies it holds, and if the study importer tools you use do not work with the new database, then a v7 upgrade is not an in-place upgrade at all. It is a re-platforming project with a data migration attached.

The reason the change was made is visible in the production note. cBioPortal production runs on ClickHouse Cloud, so the v6-to-v7 change moves the open source deployment onto the same database the hosted production system uses. For a new private instance that is a sensible alignment, because the behaviour you develop against is closer to what a public portal does. For an existing installation it converts a routine upgrade into a piece of work.

The database choice is also visible in the code as well as in the prose. The command line run in the README sets `spring.datasource.driver-class-name=com.clickhouse.jdbc.ClickHouseDriver` and `spring.jpa.database-platform=org.hibernate.dialect.ClickHouseDialect`, with a JDBC URL of `jdbc:ch://localhost:8123/cbioportal`. The `dbconnector=dbcp` property selects the connection pool, and the v6 branch uses the legacy MySQL backend with, as the README puts it, limited support.

The `docs/Migration-v6-to-v7.md` guide is referenced from the README for exactly this upgrade. It is the document that will tell you whether your importer and your data volumes make the move realistic.

Building the image and bringing it up with Compose

The quickest local setup described in the README is a two repository dance: this repository builds the image, and the docker-compose repository runs it.

First, build the development image from the cbioportal repository root, using the Dockerfile under `docker/web-and-data/`:

docker build -t cbioportal/cbioportal:my-dev-cbioportal-image -f docker/web-and-data/Dockerfile .

The tag you choose here, `my-dev-cbioportal-image` in this example, is the value you point the compose environment at. In the cbioportal-docker-compose repository you change the env file to use your image, then start the containers:

docker compose up

The application is then visible at `http://localhost:8080`. The README calls this the easiest option for deploying your development image directly into the compose file, and points at the Deploy with Docker documentation for more.

One structural detail explains why the compose file lives in another repository. The backend has a session service on port 5000 that the web app talks to, and the portal needs a database. Keeping the compose file outside this repository means the image and the orchestration can be versioned separately, which is convenient, but it also means a fresh checkout does not give you a running system on its own.

For a private instance deployment, the documentation site, `docs.cbioportal.org`, is the source referenced for setup instructions and for development environment configuration.

Running the Spring Boot app straight from the command line

If you would rather not run the portal inside Docker, the README gives a direct Java invocation. The prerequisite is that the services set up through docker compose have their ports open to the host, not just to the other containers, and the compose repository ships a file for that:

docker compose -f docker-compose.yml -f dev/open-ports.yml up

With the ports open, the backend compiles and runs with these arguments:

java -Xms2g -Xmx4g \
     -Dauthenticate=false \
     -Dsession.service.url=http://localhost:5000/api/sessions/my_portal/ \
     -Dsession.service.origin='*' \
     -Dspring.datasource.username=cbio_user \
     -Dspring.datasource.password=somepassword \
     -Dspring.datasource.driver-class-name=com.clickhouse.jdbc.ClickHouseDriver \
     -Dspring.jpa.database-platform=org.hibernate.dialect.ClickHouseDialect \
     -Dspring.datasource.url='jdbc:ch://localhost:8123/cbioportal' \
     -Dshow.civic=true \
     -Dskin.footer='' \
     -Dapp.name='my-portal' \
     -Ddbconnector=dbcp \
     -cp "$PWD:$PWD/BOOT-INF/lib/*" \
     org.cbioportal.PortalApplication

The properties are self-describing and worth reading as a configuration reference. `authenticate=false` disables authentication, which is a development convenience and a poor idea for anything reachable. The session service URL and `origin` setting point the portal at the session service on port 5000. The datasource block carries the ClickHouse driver, the ClickHouse Hibernate dialect and a JDBC URL on the default ClickHouse port 8123, with `dbcp` selecting the connection pool. `show.civic`, `skin.footer` and `app.name` are presentation settings, and `app.name` is what the session service path uses, which is why it appears in `my_portal`.

The heap settings, `-Xms2g` and `-Xmx4g`, are the first sign that this is a memory hungry application rather than a small service.

Attaching a debugger and the shared dev database

Two development aids are documented, and both have caveats that are stated in the README itself.

For debugging, the README explains that you can either add parameters to the `docker-compose.yml` file or, if you run the Java app outside Docker, to the command line arguments:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

The debug port has to be exposed by adding `5005:5005` to the ports section of the cbioportal container. A Java IDE then attaches to it, and the README gives a concrete VSCode configuration for `launch.json`:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Debug (Attach)",
            "request": "attach",
            "hostName": "localhost",
            "port": 5005,
            "projectName": "cbioportal"
        }
    ]
}

The second aid is the dev database. Internally the project keeps a dev database with the public data set that you can connect to directly, and the credentials are obtained by asking on Slack. The README's advice is to use a small test dataset in most cases, and to take a copy of the production database only when a bug is specific to production data.

That guidance is worth keeping in mind, because the distinction between the public data set and a production copy is not just a size difference. A production copy contains real patient data, and the request process through Slack is the project's way of controlling who gets one.

Testing is described as layered, separating unit, integration and end-to-end tests for clarity and control, which is a reasonable structure for a service with a database in the middle of it.

AGPL-3.0 and the cost of a v6 to v7 move

The licence is AGPL-3.0, as stated in the project metadata and the README's licence section points to the `LICENSE` file for details. The AGPL is the copyleft licence that extends GPL obligations to network use, and for an institution that runs a modified portal as a service available to users over a network, that is the clause that matters. This is a description of the licence family rather than legal advice, and the point to take away is a practical one: if you intend to modify cBioPortal and offer it to people on your network, you should read the `LICENSE` file and consult whoever handles open source compliance at your institution before you do.

The upgrade cost is where the effort actually sits, and the README is unusually direct about it. Moving from v6 to v7 means replacing the MySQL backend with ClickHouse, which the README states is not compatible with earlier portal settings, the traditional MySQL mode, or existing study importer tools. It also means a database migration for every study you hold. And on the v6 side, the promise is only security fixes, so any behavioural defect you hit there stays there.

There is a clear case where cBioPortal is the wrong tool. If your requirement is to query a specific cohort once, a portal instance is a large piece of infrastructure to stand up, with a Java backend, a session service, a database and a frontend, in front of a data set that already exists in a public instance. Running your own instance earns its keep when the data is institutional, when the studies are private, and when the analyses need to sit alongside other internal systems. Outside those conditions the cost of operating the portal is not repaid.

The alternative approach, for comparison, is the hosted public portal with its own studies, which gives you the interface and the analysis tools with none of the deployment work, at the cost of not being able to load your own cohorts. The difference in approach is exactly the difference between a web application you consume and a data platform you operate.

Editorial conclusion

Adopt `master` if you are standing up a new private portal today, because the ClickHouse-only arrangement is the only one with feature development behind it, and the migration guide referenced in the README is the documented path. Do not adopt it as an in-place upgrade of a v6 instance, since the database change is explicitly not compatible with earlier portal settings, the MySQL mode, or the existing study importer tools. Verify three things first: that the study import path you depend on works against ClickHouse, that the ClickHouse endpoint and credentials in your compose file match the ClickHouseDialect configuration the backend expects, and that the session service on port 5000 is reachable from wherever you run the web app, since the port has to be open outside the compose network for a command line run.

Frequently asked questions

Official sources

1. cBioPortal/cbioportal on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases