How to start a cellXgene instance

This document will guide you through the process of running an instance of cellxgene on a HPC or local machine.

Prerequisites

• Docker
• docker compose (which comes bundled with the base docker installation since 2023)
• a .h5ad file which has been created using scRAFIKI (other .h5ad files also supported)

Docker configuration

The docker setup only requires a single docker-compose.yml file. It references an image that comes with all dependencies pre-installed.

Abstract example

version: '3.5'

services:
  <service name>:
    image: bigdatainbiomedicine/sc-cellxgene:1.0
    expose: 
      - <port>
    network_mode: host
    volumes:
      - <host directory>:/atlas
    command: ["launch", "/atlas/<h5ad path>", "-p <port>", "--title=<title>", "-v", "--user-generated-data-dir=/atlas/annotations"]
  <service 2>:
    ...

The following elements can be adjusted to your needs:

• <service name>: Name of the docker compose service. This is not publicly visible and useful for controlling individual services via the docker compose CLI
• <port>: Port that will be passed on from the inside of the container (the actual cellxgene instance) to the host network
• <host directory>: The directory from the host system to mount into the container. The h5ad file needs to be located inside this directory. Annotations will be stored in a subdirectory of this directory called annotations.
• <h5ad path>: The path of the .h5ad file, relative to the .
• <title>: The publicly visible title of the cellxgene instance.
• <service 2>: A single docker-compose.yml file can hold any number of services, that can be jointly administrated.

An example configuration

version: '3.5'

services:
  ibd:
    image: bigdatainbiomedicine/sc-cellxgene:1.0
    expose: 
      - 5456
    network_mode: host
    volumes:
      - /localssd/cost/atlas/ibd:/atlas
    command: ["launch", "/atlas/merged.h5ad", "-p 5456", "--title=ibd-atlas", "-v", "--user-generated-data-dir=/atlas/annotations"]
  brca:
    image: bigdatainbiomedicine/sc-cellxgene:1.0
    expose: 
      - 5457
    network_mode: host
    volumes:
      - /localssd/cost/atlas/brca:/atlas
    command: ["launch", "/atlas/merged.h5ad", "-p 5457", "--title=breast-cancer-atlas", "-v", "--user-generated-data-dir=/atlas/annotations"]

Starting the setup

The services can be started using docker compose up -d (or docker-compose up -d on older versions) from within the directory in which the docker-compose.yml is located. If you navigate to localhost:<port> in your browser, you can now find the running instance of cellxgene (the port here has to be adapted depending on step 3 above). Right now, you can only access it from the local machine or within your VPN in case you run with a HPC. If you want to export this instance publicly, you will most likely talk to your local IT support about how this is handled in your lab.