An interactive explorer for single-cell transcriptomics data

Quick start
Cellxgene data portal
Demo datasets
Preparing your data
Launching cellxgene
Hosting cellxgene
Annotating data
Contributing (ideas or code)
Contact & finding help

Hosting cellxgene on the web

Cellxgene is intended to be used by researchers on their local machines. However, we recognize that sharing and exploring data on the web is important. We’re exploring how we could better support this in the future, and would welcome your input!

In the meantime, you can see examples of how other groups have approached this in our gallery. While we don’t officially support web deployment, we’ve offered some guidance below on one way to deploy cellxgene to the web.

General notes and cautions

Please consider the following when deploying cellxgene in any “hosted” environment, especially where access from the broader Internet is possible:

If you believe you have found a security-related issue with cellxgene, please report the issue immediately to security@chanzuckerberg.com.

Configuration options

The following configuration options require special consideration in any multi-user or hosted environment:

--disable-diffexp: the differential expression computation can be resource intensive, in particular for large datasets. If many differential expression calculation requests are made in rapid sequence, it may cause the server CPU or memory resources to be exhausted, and impact the ability of other users to access data. This command line option will disable the differential expression feature, including the removal of the Differential expression button.

--disable-annotations: annotations, which is enabled by default, may not be appropriate for hosted environments. It will write to the local file system, and in extreme cases could be used to abuse (or exceed) file system capacity on the hosting server. We recommend disabling this with this flag.

--annotations-file: this specifies a single file for all end-user annotations, and is incompatible with hosted or multi-user use of cellxgene. Using it will cause loss of user annotation data (ie, the CSV file will be overwritten). If you wish to explore using the annotations feature in a multi-user environment, please refer to the annotations documentation, and in particular the --annotations-dir flag.

Community software projects

There are a number of teams building tools or infrastructure to better utilize cellxgene in a multiple user environment. While we do not endorse any particular solution, you may find the following helpful.

If you know of other solutions, drop us a note and we’ll add to this list.

Deploying cellxgene with Heroku

Heroku Support

The cellxgene team has decided to end our support for our experimental deploy to Heroku button as we move towards providing a supported method of hosted cellxgene.

While we no longer directly support Heroku, it is still possible to create a Heroku app via our provided Dockerfile here and Heroku’s documentation.

You may have to tweak the Dockerfile like so:

FROM ubuntu:bionic


RUN apt-get update && \
    apt-get install -y build-essential libxml2-dev python3-dev python3-pip zlib1g-dev python3-requests && \
    pip3 install cellxgene

# ENTRYPOINT ["cellxgene"]  # Heroku doesn't work well with ENTRYPOINT

and provide a heroku.yml file similar to this:

    web: Dockerfile
      - cellxgene launch --host --port $PORT $DATASET # the DATATSET config var must be defined in your dashboard settings.

What is Heroku?

Heroku is a quick and easy way to host applications on the cloud.

A Heroku deployment of cellxgene means that the app is not running on your local machine. Instead, the app is installed, configured, and run on the Heroku servers (read: cloud).

On Heroku’s servers, applications run on a dyno which are Heroku’s implementation and abstraction of containers.

Heroku is one of many options available for hosting instances of cellxgene on the web. Some other options include: Amazon Web Services, Google Cloud Platform, Digital Ocean, and Microsoft Azure.

Why use Heroku to deploy cellxgene?

What Heroku enables is a quick, non-technical method of setting up a cellxgene instance. No command line knowledge needed. This also allows machines to access the instance via the internet, so sharing a visualized dataset is as simple as sharing a link.

Because cellxgene currently heavily relies on its Python backend for providing the viewer with the necessary data and tooling, it is currently not possible to host cellxgene as a static webpage.

This is a good option if you want to quickly deploy an instance of cellxgene to the web. Heroku deployments are free for small datasets up to around 250MBs in size. See below regarding larger datasets.

When should I not deploy with Heroku?