CINXE.COM

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en-US" prefix="og: http://ogp.me/ns#">  <head> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Language" content="en-us" /> <meta name="robots" content="all" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="description" content="The Bioconductor project aims to develop and share open source software for precise and repeatable analysis of biological data. We foster an inclusive and collaborative community of developers and data scientists." /> <title>Bioconductor - Docker for Bioconductor</title> <link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/default.min.css"> <link rel="stylesheet" href="/style/existing.css" />  <link rel="stylesheet" type="text/css" href="/style/base/fonts.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/base/colors.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/base/typography.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/base/layout.css" media="screen" />  <link rel="stylesheet" type="text/css" href="/style/components/code.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/components/gallery.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/components/blockquote.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/components/lists.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/components/breadcrumbs.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/components/buttons.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/components/tables.css" media="screen" />  <link rel="stylesheet" type="text/css" href="/style/sections/announcement.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/sections/hero.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/sections/header.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/sections/sidebar.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/sections/footer.css" media="screen"/>  <link rel="stylesheet" type="text/css" href="/style/pages/home.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/pages/get-started.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/pages/learn-and-dev.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/pages/about.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/style/pages/packages.css" media="screen"/> <link rel="SHORTCUT ICON" type="image/x-icon" href="/favicon.ico" /> <link rel="ICON" type="image/x-icon" href="/favicon.ico" /> </head> <body>  <script async src="https://www.googletagmanager.com/gtag/js?id=G-WJMEEH1J58"></script> <script> window.dataLayer = window.dataLayer || []; function gtag() { dataLayer.push(arguments); } gtag("js", new Date()); gtag("config", "G-WJMEEH1J58"); </script> <script type="text/javascript" src="/js/jquery.js"></script> <script src="/js/jquery.tools.min.js"></script> <script type="text/javascript" src="/js/bioconductor.js"></script> <script type="text/javascript" src="/js/jquery.corner.js"></script> <script type="text/javascript" src="/js/jquery.timeago.js"></script> <script type="text/javascript" src="/js/bioc-style.js"></script> <script type="text/javascript" src="/js/versions.js"></script> <script type="text/javascript" src="/js/code_blocks.js"></script> <script type="text/javascript" src="/js/sidebar.js"></script> <script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script> <header id="site-masthead" class="site-masthead"> <div class="announcement announcement-brand"> </div>  <div class="header-size"> <div class="header-logo"> <a href="/"> <img src="/images/logo/svg/Logo.svg" class="masthead-logo" alt="Bioconductor home" /> </a> </div> <nav class="header-nav"> <div class="nav-links"> <a class="format-bold mobile-link" href="/about/">About</a> <a class="format-bold mobile-link" href="/help/">Learn</a> <a class="format-bold mobile-link" href="/packages/release/BiocViews.html#___Software">Packages</a> <a class="format-bold mobile-link" href="/developers/">Developers</a> </div> <div class="search-container"> <form class="site-search" id="search-form" method="GET" action="/help/search/index.html" > <label for="search-bar" class="sr-only">Search</label> <img src="/images/icons/search-icon.svg" class="search-icon" alt="Search icon" aria-hidden="true" /> <input class="search-bar" name="search-bar" placeholder="Search" id="search-bar" /> </form> </div> <a class="header-button format-bold mobile-link" href="/install/"> <span class="get-started format-bold"> Get Started <svg xmlns="http://www.w3.org/2000/svg" width="14" height="15" viewBox="0 0 14 15" fill="none" > <path d="M5.25 3.66665L9.33333 7.74998L5.25 11.8333" stroke="#3792AD" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" /> </svg> </span> </a> </nav> <div class="nav-mobile"> <h6>Menu</h6> <div class="hamburger"> <span class="bar"></span> <span class="bar"></span> <span class="bar"></span> </div> </div> </div> </header> <main> <div class="container main-subnav"> <section class="left-col"> <div class="left-col-inner"> <div class="sidebar-nav-container"> <div class="sidebar-nav"> <span class="sidebar-header"> <p class="format-bold">Jump to:</p> <img class="mobile-chevron" src="/images/icons/chevron-down.jpg" alt="collapse-chevron" /> </span> <nav class="internal-nav" aria-label="Page navigation"> <a class="sidebar-nav-button selected-nav" href="#quick-start" >Quick start </a> <a class="sidebar-nav-button" href="#why-use-containers" >Why Use Containers</a > <a class="sidebar-nav-button" href="#goals-for-new-container-architecture" >Goals for new containers </a> <a class="sidebar-nav-button" href="#current-containers" >Current Containers </a> <a class="sidebar-nav-button" href="#using-the-containers" >Using Containers</a > <a class="sidebar-nav-button" href="#list-running-containers" >Running Containers </a> <a class="sidebar-nav-button" href="#mounting-additional-volume"> Mounting Additional Volume </a> <a class="sidebar-nav-button" href="#using-docker-compose"> Using docker-compose </a> <a class="sidebar-nav-button" href="#using-binary-packages"> Using Binary Packages </a> <a class="sidebar-nav-button" href="#modifying-containers" >Modifying Containers </a> <a class="sidebar-nav-button" href="#singularity">Singularity </a> <a class="sidebar-nav-button" href="#microsoft-azure-container-instances"> Microsoft Azure Container Instances </a> <a class="sidebar-nav-button" href="#using-containers-hosted-on-microsoft-container-registry"> Using containers hosted on Microsoft Container Registry </a> <a class="sidebar-nav-button" href="#use-azure-container-instances-to-run-bioconductor-images-on-demand-on-azure"> Use Azure Container Instances to run bioconductor images on-demand on Azure </a> <a class="sidebar-nav-button" href="#how-to-contribute" >How to contribute </a> <a class="sidebar-nav-button" href="#deprecation-notice" >Deprecation Notice</a > <a class="sidebar-nav-button" href="#legacy-containers" >Legacy Containers </a> <a class="sidebar-nav-button" href="#reason-for-deprecation" >Reason for deprecation </a> <a class="sidebar-nav-button" href="#reporting-issues" >Reporting issues </a> <a class="sidebar-nav-button" href="#acknowledgements"> Acknowledgements </a> </nav> </div> </div> </div> </section> <section class="content"> <ul class="breadcrumbs"> <li><a href="/">Home</a></li> <li><a href="/help/">Help</a></li> <li>Docker for Bioconductor</li> </ul> <h1 id="docker-containers-for-bioconductor">Docker containers for Bioconductor</h1> <p><a href="https:/docs.docker.com/engine/docker-overview/">Docker</a> packages software into self-contained environments, called containers, that include necessary dependencies to run. Containers can run on any operating system including Windows and Mac (using modern Linux kernels) via the <a href="https://docs.docker.com/engine/">Docker engine</a> or <a href="https://www.docker.com/products/docker-desktop">Docker Desktop</a>.</p> <p>Containers can also be deployed in the cloud using <a href="https://aws.amazon.com/ecs/">Amazon Elastic Container Service</a>, <a href="https://cloud.google.com/kubernetes-engine/">Google Kubernetes Engine</a> or <a href="https://azure.microsoft.com/en-us/services/container-instances/">Microsoft Azure Container Instances</a></p> <h2 id="quick-start">Quick start</h2> <ol> <li> <p><a href="https://docs.docker.com/engine/install/">Install Docker Engine</a> or <a href="https://www.docker.com/products/docker-desktop">Docker Desktop</a></p> </li> <li> <p>Run container with Bioconductor and RStudio</p> <pre><code>docker run \ -e PASSWORD=bioc \ -p 8787:8787 \ bioconductor/bioconductor_docker:devel </code></pre> </li> </ol> <p>This command will run the Docker container <code>bioconductor/bioconductor_docker:devel</code> on your local machine.</p> <p>RStudio will be available on your web browser at <code>http://localhost:8787</code>. The USER is fixed to always being <code>rstudio</code>. The password in the above command is given as <code>bioc</code> but it can be set to anything. <code>8787</code> is the port being mapped between the Docker container and your host machine. NOTE: password cannot be <code>rstudio</code>.</p> <p>The user is logged into the <code>rstudio</code> user by default.</p> <p><a name="intro"></a></p> <h2 id="why-use-containers">Why use Containers</h2> <p>Bioconductor containers enhance:</p> <ul> <li> <p><strong>Reproducibility</strong>: Containers run with pre-installed versions of R and Bioconductor. These versions do not change and can be run at any time in the future as long as the Bioconductor <code>RELEASE_X_Y</code> version tag is noted.</p> </li> <li> <p><strong>Ease of use</strong>: With one command can run either release or devel versions of Bioconductor with support for nearly all package system dependencies.</p> </li> <li> <p><strong>Convenience</strong>: Run tests with a fresh R session and a minimal set of pre-installed packages. Quickly run analyses from atypical workflows with pre-installed system dependencies.</p> </li> <li> <p><strong>Package Installation</strong>: Bioconductor publishes binary packages for fast installation of packages within containers (<code>RELEASE_3_14</code> and newer). Binary packages do not require compilation and install about 7 to 8 times faster than source package installations.</p> </li> </ul> <p>Bioconductor provides up-to-date containers for the current release and devel versions and supports older release versions. Bioconductor’s Docker images are stored in <a href="https://hub.docker.com/u/bioconductor">Docker Hub</a>; the source <code>Dockerfile</code>(s) are on <a href="https://github.com/Bioconductor/bioconductor_docker">Github</a>.</p> <p>Our release images and devel images rely on <a href="https://www.rocker-project.org/">Rocker Project</a> - <a href="https://github.com/rocker-org/rocker/tree/master/rstudio">rocker/rstudio</a> images and are built after Bioconductor releases.</p> <p><a name="goals"></a></p> <h3 id="goals-for-new-container-architecture">Goals for new container architecture</h3> <p>A few of our key goals to migrate to a new set of Docker containers are,</p> <ul> <li> <p>to keep the image size being shipped by the Bioconductor team at a manageable size.</p> </li> <li> <p>easy to extend, so developers can just use a single image to inherit and build their Docker image.</p> </li> <li> <p>easy to maintain, by streamlining the Docker inheritance chain.</p> </li> <li> <p>Adopt a “best practices” outline so that new community contributed Docker images get reviewed and follow standards.</p> </li> <li> <p>Adopt a deprecation policy and life cycle for images similar to Bioconductor packages.</p> </li> <li> <p>Replicate the Linux build machines on the <code>bioconductor/bioconductor_docker:devel</code> image as closely as possible. While this is not fully possible just yet, this image can be used by maintainers who wish to reproduce errors seen on the Bioconductor Linux build machine and as a helpful debugging tool.</p> </li> </ul> <p><a name="current"></a></p> <h2 id="current-containers">Current Containers</h2> <p>For each supported version of Bioconductor, we provide</p> <ul> <li> <p><strong>bioconductor/bioconductor_docker:RELEASE_X_Y</strong></p> </li> <li> <p><strong>bioconductor/bioconductor_docker:devel</strong></p> </li> </ul> <p><a name="usage"></a></p> <h2 id="using-the-containers">Using the containers</h2> <p>A well organized guide to popular docker commands can be found <a href="https://github.com/wsargent/docker-cheat-sheet">here</a>. For convenience, below are some commands to get you started. The following examples use the <code>bioconductor/bioconductor_docker:devel</code> image.</p> <h5 id="list-which-docker-machines-are-available-locally">List which Docker machines are available locally</h5> <pre><code>docker images </code></pre> <h5 id="list-running-containers">List running containers</h5> <pre><code>docker ps </code></pre> <h5 id="list-all-containers">List all containers</h5> <pre><code>docker ps -a </code></pre> <h5 id="resume-a-stopped-container">Resume a stopped container</h5> <pre><code>docker start <CONTAINER ID> </code></pre> <h5 id="shell-into-a-running-container">Shell into a running container</h5> <pre><code>docker exec -it <CONTAINER ID> /bin/bash </code></pre> <h5 id="shutdown-container">Shutdown container</h5> <pre><code>docker stop <CONTAINER ID> </code></pre> <h5 id="delete-container">Delete container</h5> <pre><code>docker rm <CONTAINER ID> </code></pre> <h5 id="delete-image">Delete image</h5> <pre><code>docker rmi bioconductor/bioconductor_docker:devel </code></pre> <p><a name="running"></a></p> <h3 id="running-a-bioconductor-container">Running a Bioconductor container</h3> <p>The above commands can be helpful but the real basics of running a Bioconductor Docker involves pulling the public image and running the container.</p> <h5 id="download-a-public-docker-image">Download a public Docker image</h5> <pre><code>docker pull bioconductor/bioconductor_docker:devel </code></pre> <h5 id="to-run-the-rstudio-server">To run the RStudio server:</h5> <pre><code>docker run -e PASSWORD=<password> \ -p 8787:8787 \ bioconductor/bioconductor_docker:devel </code></pre> <p>Open a web browser and browse to <code>http://localhost:8787</code> or <code>http://127.0.0.1:8787</code> (where <code>8787</code> is the port number specified in the <code>docker run</code> command).</p> <p>Set the RStudio password with <code>-e PASSWORD=</code> (required). The password is arbitrary since the container is running locally but it cannot be <code>rstudio</code>. Log in to RStudio with the username <code>rstudio</code> and the password specified in the <code>docker run</code> command.</p> <p>If you want to run RStudio as a user on your host machine, in order to read and write files in a host directory, please see the shared volumes <a href="https://rocker-project.org/use/shared_volumes.html">documentation</a>.</p> <p>NOTE: If you forget to add the tag <code>devel</code> or <code>RELEASE_X_Y</code> while using the <code>bioconductor/bioconductor_docker</code> image, it will automatically use the <code>latest</code> tag which points to the latest <code>RELEASE_X_Y</code> version of Bioconductor.</p> <h5 id="to-run-r-from-the-command-line">To run R from the command line:</h5> <pre><code>docker run -it --user rstudio bioconductor/bioconductor_docker:devel R </code></pre> <h5 id="to-open-a-bash-shell-on-the-container">To open a Bash shell on the container:</h5> <pre><code>docker run -it --user rstudio bioconductor/bioconductor_docker:devel bash </code></pre> <p><strong>Note</strong>: For full documentation, type <code>docker run --help</code> or visit the <a href="https://docs.docker.com/engine/containers/run/">help page</a>.</p> <p class="back_to_top">[ <a href="#top">Back to top</a> ]</p> <p><a name="mounting"></a></p> <h3 id="mounting-additional-volume">Mounting Additional Volume</h3> <p>Use the <code>-v</code> flag with <code>docker run</code> to mount a volume to the Docker image. This is useful to keep a more permanent R package installation directory to use with Docker. Always map the local directory to the path on the Docker image that corresponds to the local R library: <code>/usr/local/lib/R/host-site-library</code>.</p> <p>The following example mounts and maps a designated folder for container-installed packages to the Docker directory. Using the designated <code>host-site-library</code> folder ensures that the path is automatically picked up by R and shown via <code>.libPaths()</code> in the Docker image.</p> <pre><code> docker run -it \ -e PASSWORD=<password> \ -v /home/user/docker-devel-packages:/usr/local/lib/R/host-site-library \ -p 8787:8787 \ bioconductor/bioconductor_docker:devel bash </code></pre> <p>The <code>-it</code> flag gives you an interactive tty (shell/terminal) to the Docker container.</p> <ul> <li> <p>Running it with RStudio interface</p> <pre><code>docker run \ -v /home/user/docker-devel-packages:/usr/local/lib/R/host-site-library \ -e PASSWORD=password \ -p 8787:8787 \ bioconductor/bioconductor_docker:devel </code></pre> </li> </ul> <p><a name="dockercompose"></a></p> <h3 id="using-docker-compose">Using docker-compose</h3> <p><strong>Note</strong>. Ensure that <code>docker-compose</code> is installed. Docker recommends installing <code>Docker Desktop</code> to get <code>docker-compose</code>.</p> <p>The <code>Bioconductor/bioconductor_docker</code> repository has a <code>docker-compose.yaml</code> file that can be used to run the Bioconductor Docker image with the command:</p> <pre><code>docker-compose up </code></pre> <p>Within the same directory, the user can run <code>docker-compose</code> to launch the Bioconductor Docker image and access it via <code>http://localhost:8787</code>.</p> <p>The <code>docker-composer.yaml</code> includes pre-configured settings for the the port (<code>8787</code>), password (default is <code>bioc</code>), and the volume for storing container R packages.</p> <p>The configuration sets the local library folder to <code>$HOME/R/bioconductor_docker/<bioconductor_version></code>. For example, if the the Bioconductor version is <code>3.13</code>, the local library folder will be <code>$HOME/R/bioconductor_docker/3.13</code>. This location is mapped and mounted to <code>/usr/local/lib/R/host-site-library</code> in the container. Ensure that the <code>host-site-library</code> is available by running <code>.libPaths()</code> within in the container.</p> <p>When the user starts the Docker image using <code>docker-compose</code>, it will recognize previously mounted libraries with the appropriate Bioconductor version, and save users time re-installing previously installed packages.</p> <p>To add another volume, modify the <code>docker-compose.yml</code> to include another volume. For example, to add a volume for the user’s home directory, add the following line to the <code>docker-compose.yml</code> file:</p> <pre><code>volumes: - ${HOME}/R/bioconductor_docker/3.13:/usr/local/lib/R/host-site-library - ${HOME}/dockerhome:/home/rstudio </code></pre> <p>To run in the background, use the <code>-d</code> or <code>--detach</code> flag:</p> <pre><code>docker-compose up -d </code></pre> <p>If the image is run in the background, the <code>container-name</code> can be used to <code>exec</code> into the container terminal with <code>root</code> access. Run the following command to get the <code>container-name</code>:</p> <pre><code>docker ps -a </code></pre> <p>The <code>docker exec</code> command allows the user to install additional system-level dependencies with <code>root</code> access:</p> <pre><code>docker exec -it <container-name> bash </code></pre> <p>For more information on how to use <code>docker-compose</code>, use the <a href="https://docs.docker.com/compose/reference/up/">official docker-compose reference</a>.</p> <p class="back_to_top">[ <a href="#top">Back to top</a> ]</p> <p><a name="modify"></a></p> <h2 id="modifying-docker-images">Modifying Docker Images</h2> <p>There are two ways to modify Docker images:</p> <ol> <li> <p>Making changes in a running container and then committing them using the <code>docker commit</code> command.</p> <pre><code>docker commit <CONTAINER ID> <name for new image> </code></pre> </li> <li> <p>Using a <code>Dockerfile</code> to formalize the changes you want to make.</p> </li> </ol> <p>Using a <code>Dockerfile</code> is the recommended way to modify and even extend a Docker image. For more details, see the <a href="https://docs.docker.com/get-started/docker-concepts/building-images/">documentation</a>.</p> <h3 id="use-case-python-package-installation">Use case: Python package installation</h3> <p>An example scenario may be to add the <code>tensorflow</code> Python package to the <code>bioconductor/bioconductor_docker:devel</code> image and at the same time install the <code>scAlign</code> Bioconductor package on top of the base Docker image.</p> <p>First, the <code>Dockerfile</code> could inherit from the <code>bioconductor/bioconductor_docker:devel</code> image. Note that some knowledge of Linux is required to install the <code>tensorflow</code> package on the Ubuntu image.</p> <p>In the <code>Dockerfile</code>, add the following commands:</p> <pre><code># Docker inheritance FROM bioconductor/bioconductor_docker:devel # Update apt-get RUN apt-get update \ ## Install the python package tensorflow && pip install tensorflow \ ## Remove packages in '/var/cache/' and 'var/lib' ## to remove side-effects of apt-get update && apt-get clean \ && rm -rf /var/lib/apt/lists/* # Install required Bioconductor package RUN R -e 'BiocManager::install("scAlign")' </code></pre> <p>Then build the <code>Dockerfile</code> with the command:</p> <pre><code>docker build -t bioconductor_docker_tensorflow:devel . </code></pre> <p>Note that the image name is arbitrary (e.g., <code>bioconductor_docker_tensorflow</code>).</p> <p>Once built, the image can be run with the command:</p> <pre><code>docker run -p 8787:8787 -e PASSWORD=bioc bioconductor_docker_tensorflow:devel </code></pre> <h3 id="use-case-adding-latex-to-the-docker-image">Use case: Adding LaTeX to the Docker image</h3> <p>Another potential use case could be to add LaTeX to the Docker image. LaTeX is required to build vignettes and knit documents into PDF files. The <code>Dockerfile</code> could look like the following:</p> <pre><code># This docker image has LaTeX to build the vignettes FROM bioconductor/bioconductor_docker:devel # Update apt-get RUN apt-get update \ && apt-get install -y --no-install-recommends apt-utils \ && apt-get install -y --no-install-recommends \ texlive \ texlive-latex-extra \ texlive-fonts-extra \ texlive-bibtex-extra \ texlive-science \ texi2html \ texinfo \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* ## Install BiocStyle RUN R -e 'BiocManager::install("BiocStyle")' </code></pre> <p>Then build the <code>Dockerfile</code> with the command:</p> <pre><code>docker build -t bioconductor_docker_latex:devel . </code></pre> <p>Once built, the image can be run with the command:</p> <pre><code>docker run -p 8787:8787 -e PASSWORD=bioc bioconductor_docker_latex:devel </code></pre> <p class="back_to_top">[ <a href="#top">Back to top</a> ]</p> <p><a name="binarypackages"></a></p> <h3 id="using-binary-packages">Using Binary Packages</h3> <p>Binary packages are available for Bioconductor containers starting from <code>RELEASE_3_14</code>. This means that, for all <code>RELEASE_3_14</code> and newer images, Bioconductor packages will be pre-compiled and installed via <code>BiocManager::install()</code>, reducing the installation time significantly. Binary package installations provide a 7 to 8 times speed up compared to installing from source.</p> <p>To install binary packages, simply use <code>BiocManager::install()</code> within a Bioconductor container:</p> <pre><code>## Install binary packages on a container BiocManager::install(c('Rhtslib','SingleCellExperiment')) </code></pre> <p>Note that the container needs to be the <code>bioconductor/bioconductor_docker</code> or a derived image. To build custom images, see the <a href="#modifying-docker-images">Modifying Docker Images</a> section.</p> <p class="back_to_top">[ <a href="#top">Back to top</a> ]</p> <p><a name="singularity"></a></p> <h2 id="singularity">Singularity</h2> <p>Singularity is an alternative to Docker that is typically used on compute clusters where admin access may not be available.</p> <p>To check if <code>singularity</code> is installed on your High Performance Cluster (HPC), run the following:</p> <pre><code>module available </code></pre> <p>If Singularity is available, enable <code>singularity</code> with:</p> <pre><code>module load singularity </code></pre> <p>Then, convert a Docker image to a Singularity image with the <code>singularity pull</code> command:</p> <pre><code>singularity pull docker://bioconductor/bioconductor_docker:devel </code></pre> <p>For specific usage instructions relevant to Singularity containers see <a href="https://www.rocker-project.org/use/singularity/">https://www.rocker-project.org/use/singularity/</a>.</p> <p><a name="msft"></a></p> <h2 id="microsoft-azure-container-instances">Microsoft Azure Container Instances</h2> <p>Microsoft Azure users have the option to run containers using images on the <a href="https://github.com/microsoft/ContainerRegistry">Microsoft Container Registry</a>.</p> <blockquote> <p>Microsoft Container Registry (MCR) is the primary Registry for all Microsoft Published docker images that offers a reliable and trustworthy delivery of container images with a syndicated catalog</p> </blockquote> <p><a name="mcr"></a></p> <h3 id="using-containers-hosted-on-microsoft-container-registry">Using containers hosted on Microsoft Container Registry</h3> <p>Pull the <code>bioconductor_docker</code> image from the Microsoft Container Registry (MCR), specifying a <code>tag</code> of choice. Check the <a href="https://hub.docker.com/r/microsoft/bioconductor-bioconductor-docker/">MCR</a> for the list of tags under “Full Tag Listing”:</p> <pre><code>docker pull mcr.microsoft.com/bioconductor/bioconductor_docker:<tag> </code></pre> <p>To pull the latest image:</p> <pre><code>docker pull mcr.microsoft.com/bioconductor/bioconductor_docker:latest </code></pre> <h4 id="usage-run-rstudio-from-the-docker-container">Usage: Run RStudio from the Docker container</h4> <p>To run RStudio server, run the following and open a browser to <code>127.0.0.1:8787</code>. The default user name is <code>rstudio</code> and you can specify a password:</p> <pre><code>docker run --name bioconductor_docker_rstudio \ -v ~/host-site-library:/usr/local/lib/R/host-site-library \ -e PASSWORD='bioc' \ -p 8787:8787 \ mcr.microsoft.com/bioconductor/bioconductor_docker:latest </code></pre> <p>To run R in the container terminal:</p> <pre><code>docker run --name bioconductor_docker_rstudio \ -it \ -v ~/host-site-library:/usr/local/lib/R/host-site-library \ -e PASSWORD='bioc' \ -p 8787:8787 \ mcr.microsoft.com/bioconductor/bioconductor_docker:latest R </code></pre> <p class="back_to_top">[ <a href="#top">Back to top</a> ]</p> <p><a name="aci"></a></p> <h3 id="use-azure-container-instances-to-run-bioconductor-images-on-demand-on-azure">Use Azure Container Instances to run Bioconductor images on-demand on Azure</h3> <p><a href="https://azure.microsoft.com/en-us/services/container-instances/#features">Azure Container Instances</a> (ACI) provide a way to run Docker containers on-demand in a managed, serverless Azure environment. To learn more, see the <a href="https://docs.microsoft.com/en-us/azure/container-instances/container-instances-overview">documentation</a>.</p> <h3 id="run-bioconductor-images-using-aci">Run Bioconductor images using ACI</h3> <p><strong>Prerequisites</strong>:</p> <ol> <li> <p><a href="https://learn.microsoft.com/en-us/azure/cost-management-billing/manage/create-subscription">An Azure account and a subscription</a></p> </li> <li> <p><a href="https://learn.microsoft.com/en-us/cli/azure/install-azure-cli">Azure CLI</a></p> </li> <li> <p><a href="https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal">Resource group permissions</a></p> </li> </ol> <p>You can run Azure CLI or <code>az cli</code> <a href="https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest">commands</a> to create, stop, restart or delete container instances running any official Bioconductor image - either from Bioconductor or available on the <a href="https://hub.docker.com/r/microsoft/bioconductor-bioconductor-docker">MCR</a>. An Azure account and subscription is required. To create a free account browse to <a href="https://azure.microsoft.com/en-us/free/">https://azure.microsoft.com/en-us/free/</a>.</p> <p>To get familiar with Azure Container Instances, follow <a href="https://learn.microsoft.com/en-us/azure/container-instances/container-instances-quickstart">this tutorial</a>.</p> <p>To run the Bioconductor image hosted on the MCR, create a new resource group in the Azure subscription and then run the following command with the Azure CLI:</p> <pre><code>az container create \ --resource-group resourceGroupName \ --name mcr-bioconductor \ --image mcr.microsoft.com/bioconductor/bioconductor_docker \ --cpu 2 \ --memory 4 \ --dns-name-label mcr-bioconductor \ --ports 8787 \ --environment-variables 'PASSWORD'='bioc' </code></pre> <p>When completed, run this command to get the fully qualified domain name (FQDN):</p> <pre><code>az container show \ --resource-group resourceGroupName \ --name mcr-bioconductor \ --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \ --out table </code></pre> <p>Here we expose port <code>8787</code> on this publicly accessible FQDN. You may have to choose a different “dns-name-label” to avoid conflicts. By default, the username for RStudio is “rstudio” (as in the Bioconductor Docker image). The password is set to ‘bioc’ in the environment variable configuration. The <code>--cpu</code> and <code>--memory</code> values (in gigabytes; GB) can be configured as necessary. By default, ACI have 1 CPU and 1.5 GB of memory allocated.</p> <p>To learn more about configuring and customizing ACI, run:</p> <pre><code>az container create --help </code></pre> <h4 id="mount-azure-file-share-to-persist-analysis-data-between-sessions">Mount Azure File Share to persist analysis data between sessions</h4> <p>To persist data between analysis sessions when using ACIs, mount an <a href="https://learn.microsoft.com/en-us/azure/container-instances/container-instances-volume-azure-files">Azure file share</a> to the container. The following are steps to create an ACI that maps the <code>/home/rstudio</code> directory in RStudio from an <a href="https://learn.microsoft.com/en-us/azure/storage/files/storage-files-introduction">Azure File Share</a>:</p> <ol> <li> <p>Create an <a href="https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create">Azure Storage</a> account</p> </li> <li> <p>Create an <a href="https://learn.microsoft.com/en-us/azure/storage/files/storage-how-to-use-files-portal">Azure file share</a></p> </li> <li> <p>Get the <a href="https://learn.microsoft.com/en-us/cli/azure/storage/account/keys">storage account key</a></p> </li> </ol> <p>Using the Azure CLI, run the following commands to create the storage account and file share:</p> <pre><code># Change these four parameters as needed ACI_PERS_RESOURCE_GROUP=resourceGroupName ACI_PERS_STORAGE_ACCOUNT_NAME=storageAccountName ACI_PERS_LOCATION=eastus ACI_PERS_SHARE_NAME=fileShareName # Step1: Create the storage account with the parameters az storage account create \ --resource-group $ACI_PERS_RESOURCE_GROUP \ --name $ACI_PERS_STORAGE_ACCOUNT_NAME \ --location $ACI_PERS_LOCATION \ --sku Standard_LRS # Step2: Create the file share az storage share create \ --name $ACI_PERS_SHARE_NAME \ --account-name $ACI_PERS_STORAGE_ACCOUNT_NAME # Step3: Get the storage account key STORAGE_KEY=$(az storage account keys list \ --resource-group $ACI_PERS_RESOURCE_GROUP \ --account-name $ACI_PERS_STORAGE_ACCOUNT_NAME \ --query "[0].value" --output tsv) echo $STORAGE_KEY </code></pre> <p>Mount an Azure file share to an ACI running Bioconductor:</p> <pre><code>az container create \ --resource-group resourceGroupName \ --name mcr-bioconductor-fs \ --image mcr.microsoft.com/bioconductor/bioconductor_docker \ --dns-name-label mcr-bioconductor-fs \ --cpu 2 \ --memory 4 \ --ports 8787 \ --environment-variables 'PASSWORD'='bioc' \ --azure-file-volume-account-name storageAccountName \ --azure-file-volume-account-key $STORAGE_KEY \ --azure-file-volume-share-name fileShareName \ --azure-file-volume-mount-path /home/rstudio </code></pre> <p>When completed, run this command to get the fully qualified domain name or FQDN:</p> <pre><code>az container show \ --resource-group resourceGroupName \ --name mcr-bioconductor-fs \ --query "{FQDN:ipAddress.fqdn,ProvisioningState:provisioningState}" \ --out table </code></pre> <p>Note that the <code>/home/rstudio</code> directory is mapped to a persistent Azure file share named “fileShareName” in the storage account specified. When you stop or restart the ACI, this data will not be lost.</p> <h4 id="stop-start-restart-or-delete-containers-running-on-aci">Stop, Start, Restart or Delete containers running on ACI</h4> <p>You can run Azure CLI commands to <a href="https://learn.microsoft.com/en-us/azure/container-instances/container-instances-stop-start">stop, start, restart</a> or <a href="https://learn.microsoft.com/en-us/azure/container-instances/container-instances-quickstart#clean-up-resources">delete</a> container instances on Azure. You can find all the commands and options at <a href="https://learn.microsoft.com/en-us/cli/azure/container?view=azure-cli-latest#commands">https://learn.microsoft.com/en-us/cli/azure/container?view=azure-cli-latest#commands</a>.</p> <h5 id="stop-the-container-instance">Stop the container instance</h5> <p>Note that <code>containerName</code> and <code>resourceGroupName</code> in the following CLI commands should be replaced with the actual container name and resource group name.</p> <pre><code>az container stop -n containerName -g resourceGroupName </code></pre> <h5 id="start-the-container-instance">Start the container instance</h5> <pre><code>az container start -n containerName -g resourceGroupName </code></pre> <h5 id="restart-the-container-instance">Restart the container instance</h5> <pre><code>az container restart -n containerName -g resourceGroupName </code></pre> <h5 id="delete-the-container-instance">Delete the container instance</h5> <pre><code>az container delete -n containerName -g resourceGroupName </code></pre> <p>Use the <code>-y</code> flag to avoid the confirmation prompt when deleting the ACI:</p> <pre><code>az container delete -n containerName -g resourceGroupName -y </code></pre> <p>To troubleshoot any issues when using ACIs, see the <a href="https://learn.microsoft.com/en-us/azure/container-instances/container-instances-troubleshooting">common issues page</a>. For feedback or further issues, contact <a href="mailto:genomics@microsoft.com">genomics@microsoft.com</a>.</p> <p class="back_to_top">[ <a href="#top">Back to top</a> ]</p> <p><a name="contribute"></a></p> <h2 id="how-to-contribute">How to Contribute</h2> <p>There is a comprehensive list of best practices and standards on how community members can contribute images:</p> <p><a href="https://github.com/Bioconductor/bioconductor_docker/blob/master/best_practices.md">https://github.com/Bioconductor/bioconductor_docker/blob/master/best_practices.md</a></p> <p><a name="deprecation"></a></p> <h2 id="deprecation-notice">Deprecation Notice</h2> <p>For previous users of Docker containers for Bioconductor, please note that we are deprecating the following Bioconductor and community maintained images.</p> <p><a name="legacy"></a></p> <h3 id="legacy-containers">Legacy Containers</h3> <p>These images are <strong>NO LONGER MAINTAINED</strong>. They will however be available to use should a user choose.</p> <p>Bioconductor Core Team: bioc-issue-bot@bioconductor.org</p> <ul> <li><a href="https://hub.docker.com/r/bioconductor/devel_base2/">bioconductor/devel_base2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/devel_core2/">bioconductor/devel_core2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_base2/">bioconductor/release_base2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_core2/">bioconductor/release_core2</a></li> </ul> <p>Steffen Neumann: sneumann@ipb-halle.de, Maintained as part of the “PhenoMeNal, funded by Horizon2020 grant 654241”</p> <ul> <li><a href="https://hub.docker.com/r/bioconductor/devel_protmetcore2/">bioconductor/devel_protmetcore2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/devel_metabolomics2/">bioconductor/devel_metabolomics2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_protmetcore2/">bioconductor/release_protmetcore2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_metabolomics2/">bioconductor/release_metabolomics2</a></li> </ul> <p>Laurent Gatto: lg390@cam.ac.uk</p> <ul> <li><a href="https://hub.docker.com/r/bioconductor/devel_mscore2/">bioconductor/devel_mscore2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/devel_protcore2/">bioconductor/devel_protcore2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/devel_proteomics2/">bioconductor/devel_proteomics2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_mscore2/">bioconductor/release_mscore2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_protcore2/">bioconductor/release_protcore2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_proteomics2/">bioconductor/release_proteomics2</a></li> </ul> <p>RGLab: wjiang2@fredhutch.org</p> <ul> <li><a href="https://hub.docker.com/r/bioconductor/devel_cytometry2/">bioconductor/devel_cytometry2</a></li> <li><a href="https://hub.docker.com/r/bioconductor/release_cytometry2/">bioconductor/release_cytometry2</a></li> </ul> <p>First iteration containers</p> <ul> <li>bioconductor/devel_base</li> <li>bioconductor/devel_core</li> <li>bioconductor/devel_flow</li> <li>bioconductor/devel_microarray</li> <li>bioconductor/devel_proteomics</li> <li>bioconductor/devel_sequencing</li> <li>bioconductor/devel_metabolomics</li> <li>bioconductor/release_base</li> <li>bioconductor/release_core</li> <li>bioconductor/release_flow</li> <li>bioconductor/release_microarray</li> <li>bioconductor/release_proteomics</li> <li>bioconductor/release_sequencing</li> <li>bioconductor/release_metabolomics</li> </ul> <p><a name="reason"></a></p> <h3 id="reason-for-deprecation">Reason for deprecation</h3> <p>The new Bioconductor Docker image <code>bioconductor/bioconductor_docker</code> has nearly all system dependencies pre-installed. This makes it possible to install any package and avoids the need for multiple images with different system dependencies. Packages can be installed with <code>BiocManager::install()</code>.</p> <p>Other reasons for deprecation:</p> <ul> <li> <p>the chain of inheritance of Docker images was too complex and hard to maintain</p> </li> <li> <p>images were hard to extend because there were multiple flavors</p> </li> <li> <p>naming convention was not consistent</p> </li> <li> <p>unused images were not deprecated</p> </li> </ul> <p><a name="issues"></a></p> <h3 id="reporting-issues">Reporting Issues</h3> <p>To report any issues or bugs, go to the GitHub <a href="https://github.com/Bioconductor/bioconductor_docker/issues">issues page</a>.</p> <p>Feel free to ask questions related to usage, extension, and enhancement of Bioconductor images either via GitHub issues or on the <a href="mailto:bioc-devel@r-project.org">Bioc-devel</a> mailing list.</p> <p><a name="acknowledgements"></a></p> <h2 id="acknowledgements">Acknowledgements</h2> <p>Thanks to the <a href="https://github.com/rocker-org/rocker">rocker</a> project for providing the R/RStudio Server containers upon which ours are based.</p> </section> </main> <footer> <div class="footer-container"> <div class="link-container"> <div class="link-container-inner"> <nav> <a href="/about/index.html"><h3>About</h3></a> <a href="/about/annual-reports/">Annual Reports</a> <a href="/about/collaborations/">Collaborations</a> <a href="/about/core-team/">Core Team</a> <a href="/about/mirrors/">Mirrors</a> <a href="/dashboard/">Dashboard</a> <a href="/about/">Project Details</a> <a href="/about/code-of-conduct/">Code of Conduct</a> </nav> <nav> <a href="/developers/index.html"><h3>Developers</h3></a> <a href="https://contributions.bioconductor.org/develop-overview.html">Package Guidelines</a> <a href="https://contributions.bioconductor.org/submission-overview.html">Package Submission</a> <a href="/developers/release-schedule/">Release Schedule</a> <a href="/about/release-announcements/">Release Announcements</a> <a href="https://contributions.bioconductor.org/git-version-control.html">Source Control</a> <a href="https://code.bioconductor.org/">Browsable Code Base</a> <a href="/checkResults/">Build Reports</a> </nav> </div> <div class="link-container-inner"> <nav> <a href="/help/index.html"><h3>Learn</h3></a> <a href="https://training.bioconductor.org/">Education and Training</a> <a href="/help/bioconductor-books/">Bioconductor Books</a> <a href="/help/package-vignettes/">Package Vignettes</a> <a href="/packages/release/workflows/">Workflows</a> <a href="/help/publications/">Publications</a> <a href="/help/community/">Community Resources</a> <a href="/help/support/">Get Help</a> </nav> <nav> <a href="/install/index.html"><h3>Get started</h3></a> <a href="/install/index.html#install-R">Install R</a> <a href="/install/index.html#find-bioconductor-packages">Find Bioconductor Packages</a> <a href="/install/index.html#install-bioconductor-packages">Install Bioconductor Packages</a> <a href="/install/index.html#update-bioconductor-packages">Update Bioconductor Packages</a> <a href="/help/docker/">Docker Images</a> <a href="https://anvil.bioconductor.org/">Bioconductor in AnVIL</a> <a href="/packages/release/BiocViews.html#___Software">Bioconductor Packages</a> </nav> </div> </div> <div class="logo-contact-container"> <div class="copyright"> <p> Contact us: <a class="text-underline" href="https://support.bioconductor.org/">support.bioconductor.org</a><br/> Copyright © 2003 - 2025 Bioconductor </p> </div> <div class="socials-logo-container"> <div class="socials"> <a href="https://slack.bioconductor.org/" target="_blank"><img alt="Slack Logo" src="/images/icons/slack.png" /></a> <a href="https://www.youtube.com/user/bioconductor" target="_blank"><img alt="YouTube Logo" src="/images/icons/svgs/youtube.svg" /></a> <a href="https://www.linkedin.com/company/bioconductor/" target="_blank"><img alt="LinkedIn Logo" src="/images/icons/svgs/linkedin.svg" /></a> <a href="https://bsky.app/profile/bioconductor.bsky.social" target="_blank"><img alt="Bluesky Logo" src="/images/icons/svgs/bluesky.svg" /></a> <a href="https://genomic.social/@bioconductor" target="_blank"><img alt="Mastodon Logo" src="/images/icons/svgs/mastodon.svg" /></a> <a href="https://blog.bioconductor.org/" target="_blank"><img alt="Blog Logo" src="/images/icons/svgs/arrow-circle-right-white.svg" /></a> </div> <img class="footer-logo" src="/images/logo/svg/BC-Logo-White.svg" alt="BioConductor Logo in White" /> </div> </div> </div> </footer> </body> </html>