Skip to content

Running GenePattern in a Docker Container

Jump to bottom Edit New page
liefeld edited this page Apr 23, 2026 · 1 revision

Running GenePattern in a Docker Container

Since the GenePattern server (as of 2017) primarily uses Docker to encapsulate the runtime environments for its modules, Docker is required to run any modules of recent vintage. Therefore Docker is essential on a GenePattern server host whether or not the server itself is run inside a Docker container. For information about Docker itself, see the official Docker website for documentation and tutorials. The following section details considerations and steps used to run GenePattern in Docker on a Macintosh OSX computer. For running in Docker on other operating systems, similar issues and approaches should be viable.

When running the GenePattern server in Docker, or with Docker modules, you should consider the security issues involved. When modules are sent to the Docker daemon on the host, the module containers could potentially write files to any parts of the host disk drives that have been mounted to them as the root user. In the case of GenePattern, this typically means the TaskLib, Users and JobResults directories. For this reason many IT organizations do not like to allow Docker on internal servers. This can be mitigated by using Singularity instead of Docker for the module images which has been done in practice, but as of this writing (May 2020) we have not yet developed and documented a simple automated system for doing so. This security risk will be mitigated in the future as it is possible to both run the Docker daemon under a user account, and to set up networking without privileged mode, when running Docker on Linux. We will update these instructions once that is available on Macintosh OSX.

Running modules on the host Docker daemon has the advantage that each module runs in its own separate container allowing better utilization of compute resources and, if a Docker swarm or other distributed Docker system is in play, module executions can easily be distributed to multiple computers or virtual machines.

Windows 10 Setup Instructions

For Windows 10, installation of Docker requires WSL (Windows Subsystem for Linux) version 2 as described in the Docker documentation. To use the start-genepattern.sh script described below, you will also need to make sure that your default WSL distribution is also version 2. To check, run wsl -l -v.

For example:

C:\Users\liefeld> wsl -l -v
  NAME                   STATE           VERSION
* Ubuntu                 Running         2
  docker-desktop-data    Running         2
  docker-desktop         Running         2

If your default is using version 1, you can change it using the following two commands (assuming your default distribution is Ubuntu):

wsl set-version Ubuntu 2
wsl set-default-version 2

Once this is done you can start WSL at a PowerShell prompt:

wsl

and follow the instructions for Linux/macOS platforms below.

Note: The start-genepattern.sh script will not run properly in PowerShell due to the different slashes used for file system paths between Windows and Linux. You must either start WSL first and execute it there, or use bash .\start-genepattern.sh at a PowerShell prompt, which will use bash within WSL to execute the script rather than PowerShell itself.

Overview of Running GenePattern Server in Docker

When running GenePattern Server from a Docker container, it is assumed that this is desired to be a persistent GenePattern installation. Therefore the details of jobs run and analysis output files are kept external to the Docker container. This allows them to remain accessible even if the server container is deleted, and to be connected to updated versions of the container as they become available. The directories that are kept external are: gp_runner/log_parser.py

  1. users — where uploaded user files are kept
  2. jobResults — where job output files are kept
  3. taskLib — where module code for legacy (pre-Docker) modules is kept
  4. resources — where configuration files are kept; also holds the GenePattern database if the default HSQL database is used

Latest versions of scripts and example configuration files referenced below are available at: https://github.com/genepattern/genepattern-server/tree/develop/docker When running the GenePattern server in Docker, the following configuration changes are made (relative to the default installation using the installer):

  • <genepattern_home>/resources/wrapper_scripts/run-with-docker.sh is set as the default command-line prefix.
  • job.docker.bind_src is set to your local <genepattern_home> directory. This directory (and its subdirectories) will be writable to the GenePattern server and module containers.
  • job.docker.bind_dst is set to /opt/genepattern. This is the mounting point for your <genepattern_home> directory within the module containers.

Steps for Running GenePattern in Docker on a Host Computer

The following steps were developed on a Macintosh OSX laptop. The scripts should work on most Linux installations with the bash shell installed, but the scripts can be customized as needed for other environments. We recommend that Windows users run the GenePattern server container from WSL.*

  1. Decide on the GenePattern server container version you wish to run. GenePattern server containers are publicly available on Docker Hub and use a versioning system that matches the GitHub releases for the project.

    Copy or make note of the version tag you have selected, e.g. v3.9_21.04.05_b325.

  2. Create a root server directory for the GenePattern installation. All GenePattern files and folders will be created in or below this directory.

  3. Copy the start-genepattern.sh script from the GenePattern GitHub repository into your root server directory.

  4. Run the start-genepattern.sh script. This script will pull the Docker image, create the directories, customize the config_custom.yaml for the server, and create a Docker container with the necessary port mappings and volume mounts. The desired GenePattern server tag should be passed in with the -v or --version flag:

    ./start-genepattern.sh -v v3.9_21.04.05_b325

    The container name will be genepattern but can be edited by changing the variable at the top of the script.

  5. Login to the GenePattern server at http://127.0.0.1:8080/gp and complete the installation. You will need to register your server and then install modules etc. as per a non-Docker installation.

Following installation, the server can be stopped via the usual Docker command (e.g. docker stop genepattern). Restarting the container can be done via re-running the start-genepattern.sh script or via the docker start command. When re-running the start-genepattern.sh script, it will check for a running container or a pre-existing but stopped GenePattern container rather than creating a new installation.

*Running GenePattern in Docker from Windows (without WSL)

If you choose to run GenePattern in Docker from Windows without using WSL, you will need to alter the Docker run command. The steps are as follows:

  1. Run steps 1–4 above (note: your server will not start).

  2. Copy the docker run command from the second-to-last line of the start-genepattern.sh script.

  3. In a terminal or text editor, replace all instances of $PWD in the run command with the Unix version of your root server directory for GenePattern. For example, if you created a root server directory C:\Users\Me\gp_home, the Unix version would be /c/Users/Me/gp_home.

  4. Replace $name with genepattern and $VERSION with the version of the GenePattern server Docker container you created when you first ran the start-genepattern.sh script. It will look like this:

    docker run \
  -v /c/Users/Me/gp_home:/c/Users/Me/gp_home \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -w /c/Users/Me/gp_home \
  -v /c/Users/Me/gp_home/resources:/opt/genepattern/resources \
  -v /c/Users/Me/gp_home/taskLib:/opt/genepattern/taskLib \
  -v /c/Users/Me/gp_home/jobResults:/opt/genepattern/jobResults \
  -v /c/Users/Me/gp_home/users:/opt/genepattern/users \
  -p 8888:8888 -p 8080:8080 \
  -d --name "genepattern" \
  genepattern/genepattern-server:v3.9_21.07_b352 \
  /opt/genepattern/StartGenePatternServer

  5. Run that command in the terminal (preferably PowerShell) and then navigate to http://127.0.0.1:8080/gp in a browser window.

Changing the Server Version Container

When you wish to upgrade the version of the GenePattern server container, you will want to save your users, uploaded files, job results and configuration. This is built into the start-genepattern.sh script, which will preserve and reuse the following files (if run in the same directory as the previous version):

  • users/ directory
  • jobResults/ directory
  • taskLib/ directory
  • resources/genepattern.properties
  • resources/database_custom.properties
  • resources/config_custom.yaml
  • resources/userGroups.xml
  • resources/PermissionsMap.xml
  • resources/GenepatternDB.properties
  • resources/GenePatternDB.script

The process to update the GenePattern server to a newer version of the container is as follows:

  1. Stop the running server:

    docker stop genepattern

  2. Remove the old container:

    docker rm genepattern

  3. Start a new container with the desired version using the start-genepattern.sh script and the new version tag:

    start-genepattern.sh -v v3.9_21.04.05_b325

  4. Login to the GenePattern server at http://127.0.0.1:8080/gp and commence using it.

Add a custom footer
Add a custom sidebar

Clone this wiki locally