5b54eba6619b55ebe18c183dbc65c26e7da82e18 mspeir Thu Sep 3 09:39:15 2026 -0700 docker help: promote the prebuilt image section to h2 and split out the build path Code review pointed out that the section 3334b0d added was an h3 nested under "Using Docker Desktop for UCSC Genome Browser" while every other entry in the page's table of contents is an h2. It is now an h2. That alone left the four build-your-own h3s that follow it (Obtaining a Dockerfile, Creating a Image, Creating a Container, Using Docker Desktop to Create a Container) nested under the prebuilt image section, which is the wrong parent since they describe building rather than pulling. They now sit under a new "Building the Image Yourself" h2, which also gets a table of contents entry. Every h2 on the page is now listed in the contents and every h3 is under the h2 it belongs to. refs #37764 Co-Authored-By: Claude Opus 5 (1M context) diff --git src/hg/htdocs/goldenPath/help/docker.html src/hg/htdocs/goldenPath/help/docker.html index 02c596a24ad..bef13673a50 100755 --- src/hg/htdocs/goldenPath/help/docker.html +++ src/hg/htdocs/goldenPath/help/docker.html @@ -1,30 +1,31 @@

Docker Help Page

Contents

What is Docker?
How to Install Docker Desktop?
Using Docker Desktop for UCSC Genome Browser
Using the Prebuilt UCSC Genome Browser Image
+
Building the Image Yourself
Create a Docker Volume for Data Persistence
Updating the Latest UCSC Genome Browser Version
Customize a UCSC Genome Browser Docker Container

What is Docker?

Docker is a platform for developing, testing and running applications. Docker can be used to run genomics tools and manage software such as the UCSC Genome Browser. Docker offers consistency across different computers and environments by packaging everything needed including specific software versions and configurations into a self-contained unit called a container.

Container

@@ -76,60 +77,63 @@ target=_blank>system requirements
  • Follow Generic installation steps

    Using Docker Desktop for UCSC Genome Browser

    Start Docker Desktop after installation is complete:

    -

    Using the Prebuilt UCSC Genome Browser Image

    +

    Using the Prebuilt UCSC Genome Browser Image

    UCSC publishes a ready-made Genome Browser image on Docker Hub as genomebrowser/server. The image is rebuilt for every Genome Browser release and tagged with the version number, for example v502. The latest tag always points at the most recent release, and a single tag covers both Intel and Apple Silicon machines. Most people should pull this image rather than build the Dockerfile themselves, since pulling takes a few minutes where a build takes considerably longer.

    The following commands download the image and start a container, mapping port 8080 on the host machine to port 80 in the container:

    docker pull genomebrowser/server
 docker run -d --name ucsc_genomebrowser_container -p 8080:80 genomebrowser/server

    The Genome Browser is then available at http://localhost:8080

    To pull a specific release rather than the most recent one, add the version tag:

    docker pull genomebrowser/server:v502

    Plan on about 8GB of disk space for the image itself. The download is around 2.6GB and unpacks to around 7.4GB. Track data is downloaded from UCSC as you use the browser and needs space beyond that. See the Create a Docker Volume for Data Persistence section below for keeping that data between container restarts.

    Build the image from the Dockerfile instead if you need to change how it is built, for instance to add other software or to change the Genome Browser configuration at build time. The next sections describe how to do that.

    + +

    Building the Image Yourself

    +

    Obtaining a UCSC Genome Browser Dockerfile

    The UCSC Genome Browser dockerfile can be obtained from the UCSC Genome Browser Github by using the wget command:

    wget https://raw.githubusercontent.com/ucscGenomeBrowser/kent/master/src/product/installer/docker/Dockerfile

    Creating a Image

    Once the dockerfile has been downloaded, running the docker build with the 't' option allows the naming and the optional tag (format: "name:tag") of the image. The image can be created by running the following command in the same directory where the dockerfile is located:

    docker build . -t user_name/ucsc_genomebrowser_image

    Creating a Container

    After the image has been created, running the docker run command and the image with the -d option allows the container to be run in the background, whereas the default runs the container in the foreground. The -p option publishes a container's port(s) to the host. The following command