Skip to contents

Running scExploreR with Docker

Source: vignettes/docker.Rmd
docker.Rmd

scExploreR can be deployed with Docker to facilitate deployment on a server, or to facilitate sharing scExploreR instances with your data with collaborators. Deployment on docker is not required to run scExploreR. For general instructions on setting up an app instance with your data, see the Dataset Setup Walkthrough article.

This guide provides step-by-step instructions for setting up and running the scExploreR Shiny app using Docker. We’ll cover building the Docker image, understanding the file structure, configuring the application, and running the app.

scExploreR_docker Repository

All of this code is available to clone, build and run on the amc-heme/scExploreR_docker GitHub repository.

Table of Contents

  1. Prerequisites
  2. File Structure
  3. Step 1: Set Up the Dockerfile
  4. Step 2: Configure the Shiny Server
  5. Step 3: Add Object and Genetate Object Config File
  6. Step 4: Set Up the Shiny Application
  7. Step 5: Generate App Config File
  8. Step 6: Build the Docker Image
  9. Step 7: Run the Docker Container
  10. Troubleshooting
  11. References

Prerequisites

  • Docker: Ensure Docker is installed and running on your system. You can download it from the official website.

File Structure

Your project directory should have the following structure:

.
│Dockerfile
│shiny-server.conf    
└───shiny-server/
    └───project-name/
        │   app.R
        │   config.yaml
        │   object-config.yaml
        │   object.rds
  • Dockerfile: Instructions to build the Docker image.
  • shiny-server.conf: Configuration for the Shiny server.
  • shiny-server/: Directory containing the Shiny app files.
  • project-name/: Directory for the specific dataset/application.
  • app.R: Main R script to run the scExploreR app.
  • config.yaml: Configuration file specifying datasets and settings for scExploreR .
  • object-config.yaml: Configuration for the specific data object built using the scExploreR Config App.
  • object.rds: Serialized R data object containing your single-cell dataset. This may be a Seurat object, a SingleCellExperiment object, or an anndata object.

Step 1: Set Up the Dockerfile

The Dockerfile specifies the environment and dependencies required to run scExploreR.

# Dockerfile

FROM rocker/shiny-verse:latest

# Install system dependencies
RUN apt-get update \
    && apt-get install -y --no-install-recommends libglpk-dev libhdf5-dev

# Install essential R packages
RUN R -e "install.packages('Seurat'); if (!library(Seurat, logical.return=T)) quit(status=10)"
RUN R -e "remotes::install_github('bnprks/BPCells/r');  if (!library(BPCells, logical.return=T)) quit(status=10)"

# Install Bioconductor packages
RUN R -e "install.packages('BiocManager'); if (!library(BiocManager, logical.return=T)) quit(status=10)"
RUN R -e "BiocManager::install(c('SummarizedExperiment', 'HDF5Array', 'SingleCellExperiment'))"
RUN R -e "remotes::install_github('amc-heme/scExploreR');  if (!library(scExploreR, logical.return=T)) quit(status=10)"

# Install additional system dependencies
RUN apt-get install -y --no-install-recommends texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra lmodern

# Install additional R packages
RUN R -e "install.packages(c('survminer','survival','tinytex','RColorBrewer','data.table','ggpubr','reshape2','viridis'))"
RUN R -e "BiocManager::install(c('biomaRt','RTCGA.clinical'))"

# Install more R packages
RUN R -e "install.packages(c('shinythemes', 'thematic', 'kableExtra', 'TidyMultiqc', 'janitor', 'ggiraph', 'circlize', 'esquisse', 'ggprism', 'formulaic', 'heatmaply', 'bsicons'))"
RUN R -e "BiocManager::install(c('tximport','DESeq2','fgsea','BiocParallel','ComplexHeatmap','sva', 'InteractiveComplexHeatmap'))"

# Install Python dependencies using reticulate
USER shiny
RUN R -e "reticulate::install_miniconda()"
RUN . /home/shiny/.local/share/r-miniconda/bin/activate \
    && conda activate /home/shiny/.local/share/r-miniconda/envs/r-reticulate \
    && /home/shiny/.local/share/r-miniconda/envs/r-reticulate/bin/python -m pip install --upgrade --no-user anndata scanpy

USER root

# Clean up and copy app files
RUN rm -rf /srv/shiny-server
COPY shiny-server.conf /etc/shiny-server/shiny-server.conf
COPY shiny-server/ /srv/shiny-server/

Step 2: Configure the Shiny Server

The shiny-server.conf file sets up the Shiny server to host scExploreR.


# shiny-server.conf

# Run applications as the "shiny" user
run_as shiny;
http_keepalive_timeout 600;

# Define a server that listens on port 3838
server {
  listen 3838;

  # Location at the base URL
  location / {
    # Set application idle timeout
    app_idle_timeout 600;

    # Host the directory of Shiny apps
    site_dir /srv/shiny-server;

    # Log all Shiny output
    log_dir /var/log/shiny-server;

    # Show an index of applications at the base URL
    directory_index on;
  }
}

Step 3: Add Object and Generate Object Config

You can add any number of objects in your project directory. Objects may be Seurat, SingleCellExperiment, or anndata objects. Each object needs an object config file to define assays/modalities and metadata to expose to end users. The object config file is generated by running run_config_app locally on the object(s) you wish to containerize. For more information, see the Dataset Setup Walkthrough Article.

# This should be ran locally, and the output yaml generated by the config app
# should then be moved to /srv/shiny-server/project-name.
scExploreR::run_config(
  object_path = "/srv/shiny-server/project-name/object.rds"
)

Step 4: Generate App Config File

The config.yaml file specifies settings for scExploreR, and the paths of datasets to load in the app. This is the app config file (rather than the object config file). For more information on how to generate this file, see the Dataset Setup Walkthrough article.

# config.yaml

datasets:
  dataset_name:
    object: "/srv/shiny-server/project-name/object.rds"
    config: "/srv/shiny-server/project-name/object-config.yaml"

Step 5: Set up scExploreR Script

The app.R script defines how scExploreR will be ran. This file should be an R script with a call to run_scExploreR, with the browser_config parameter set to the path of the app config file created in step 4.

# app.R

setwd("/srv/shiny-server/project-name")
scExploreR::run_scExploreR(
  browser_config = "/srv/shiny-server/project-name/config.yaml", 
  launch_browser = FALSE
  )
  • setwd: Sets the working directory to where data and configuration files are located.
  • run_scExploreR: Launches the scExploreR app with the specified configuration.

Step 6: Build the Docker Image

Navigate to the directory containing the Dockerfile and run:

docker build --platform=linux/amd64 -t scexplorer .
  • --platform=linux/amd64 : Builds the image for the amd64 architecture. (remove if not using ARM Mac)
  • -t scexplorer : Tags the image with the name scexplorer.
  • . : Specifies the current directory as the build context.
Note

Build Time: Building the image may take some time as it installs several packages.

Troubleshooting: If you encounter errors, ensure that all package names and dependencies are correct.

Step 7: Run the Docker Container

Run the Docker container with the command below.

docker run --rm -p 3838:3838 scexplorer

Accessing the Application

Once the container is running, open your web browser and navigate to http://localhost:3838. You should see the scExploreR interface.

Troubleshooting

Common Issues

  • Cannot Access App: Ensure the container is running and a port 3838 is not blocked by a firewall.
  • Data Loading Errors: Verify that the paths in config.yaml and object-config.yaml are correct and that the files exist in the specified locations.

Tips

  • Check Logs: Use Docker logs to identify issues by running bash docker logs <container_id>.

  • Interactive Shell: If needed, start a shell inside the container for debugging:

docker run -it --entrypoint /bin/bash -p 3838:3838 scexplorer

References