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) <noreply@anthropic.com> 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 @@ <!DOCTYPE html> <!--#set var="TITLE" value="Docker help page" --> <!--#set var="ROOT" value="../.." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> <h1>Docker Help Page</h1> <h2>Contents</h2> <h6><a href="#docker">What is Docker?</a></h6> <h6><a href="#installingDocker">How to Install Docker Desktop?</a></h6> <h6><a href="#dockerUCSCgb">Using Docker Desktop for UCSC Genome Browser</a></h6> <h6><a href="#dockerHub">Using the Prebuilt UCSC Genome Browser Image</a></h6> +<h6><a href="#buildImage">Building the Image Yourself</a></h6> <h6><a href="#dockerVolume">Create a Docker Volume for Data Persistence</a></h6> <h6><a href="#updateGB">Updating the Latest UCSC Genome Browser Version</a></h6> <h6><a href="#hg.conf">Customize a UCSC Genome Browser Docker Container</a></h6> <!-- ========== What is Docker? ============================== --> <a id="docker"></a> <h2>What is Docker?</h2> <p> 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. <h3>Container</h3> @@ -76,60 +77,63 @@ target=_blank>system requirements</a></li> <li>Follow <a href="https://docs.docker.com/desktop/install/linux-install/#generic-installation-steps" target=_blank>Generic installation steps</a> </ul> <a id="dockerUCSCgb"></a> <h2>Using Docker Desktop for UCSC Genome Browser</h2> <p>Start Docker Desktop after installation is complete:</p> <ul> <li><b>Windows</b>: start Docker Desktop from the Start menu <li><b>macOS</b>: start Docker Desktop from the Applications folder <li><b>Linux</b>: start the Docker service by running the following command on the terminal: <pre><code>sudo systemctl start docker</pre></code> </ul> <a id="dockerHub"></a> -<h3>Using the Prebuilt UCSC Genome Browser Image</h3> +<h2>Using the Prebuilt UCSC Genome Browser Image</h2> <p> UCSC publishes a ready-made Genome Browser image on Docker Hub as <a href="https://hub.docker.com/r/genomebrowser/server" target=_blank>genomebrowser/server</a>. The image is rebuilt for every Genome Browser release and tagged with the version number, for example <code>v502</code>. The <code>latest</code> 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.</p> <p> The following commands download the image and start a container, mapping port 8080 on the host machine to port 80 in the container:</p> <pre><code>docker pull genomebrowser/server docker run -d --name ucsc_genomebrowser_container -p 8080:80 genomebrowser/server</code></pre> <p>The Genome Browser is then available at http://localhost:8080</p> <p>To pull a specific release rather than the most recent one, add the version tag:</p> <pre><code>docker pull genomebrowser/server:v502</code></pre> <p> 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 <a href="#dockerVolume">Create a Docker Volume for Data Persistence</a> section below for keeping that data between container restarts.</p> <p> 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.</p> +<a id="buildImage"></a> +<h2>Building the Image Yourself</h2> + <h3>Obtaining a UCSC Genome Browser Dockerfile</h3> <p>The UCSC Genome Browser dockerfile can be obtained from the <a href="https://github.com/ucscGenomeBrowser/" target=_blank>UCSC Genome Browser Github</a> by using the wget command:</p> <pre><code>wget https://raw.githubusercontent.com/ucscGenomeBrowser/kent/master/src/product/installer/docker/Dockerfile</code></pre> <h3>Creating a Image</h3> <p> 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:</p> <pre><code>docker build . -t user_name/ucsc_genomebrowser_image</code></pre> <h3>Creating a Container</h3> <p>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