3334b0dc02b7d88cd21a987b3765b30d581339cd mspeir Wed Sep 2 14:09:21 2026 -0700 store, docker help: document the prebuilt Docker Hub image and correct the image size Braney pointed out on the ticket that neither page mentions genomebrowser/server, the image the weekly build pushes to Docker Hub (buildReleaseDocker.sh). It is rebuilt every release, latest currently points at v502, and one tag covers amd64 and arm64, so pulling it is the better path for most people than building the Dockerfile. Both pages now say so, and docker.html gains a section with the pull and run commands ahead of the build instructions. The store page said the built image is around 3GB, which was true a few releases ago. Building the current Dockerfile gives about 5.6GB on disk, and the published image is a 2.6GB download that unpacks to about 7.4GB, so the page now tells people to plan on 8GB for the image alone, separate from track data. 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 06ed38094d9..02c596a24ad 100755 --- src/hg/htdocs/goldenPath/help/docker.html +++ src/hg/htdocs/goldenPath/help/docker.html @@ -1,29 +1,30 @@ <!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="#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> @@ -74,30 +75,61 @@ <li>Check <a href="https://docs.docker.com/desktop/install/linux-install/#system-requirements" 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> +<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> + <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