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>.</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>Install Docker</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> <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> </li> </ol> <p><a name="intro"></a></p> <h2 id="why-use-containers">Why use Containers</h2> <p>With Bioconductor containers, we hope to enhance</p> <ul> <li> <p><strong>Reproducibility</strong>: If you run some code in a container today, you can run it again in the same container (with the same <a href="https://docs.docker.com/userguide/dockerimages/#setting-tags-on-an-image">tag</a>) years later and know that nothing in the container has changed. You should always take note of the tag you used if you think you might want to reproduce some work later.</p> </li> <li> <p><strong>Ease of use</strong>: With one command, you can be running the latest release or devel Bioconductor. No need to worry about whether packages and system dependencies are installed.</p> </li> <li> <p><strong>Convenience</strong>: Easily start a fresh R session with no packages installed for testing. Quickly run an analysis with package dependencies not typical of your workflow. Containers make this easy.</p> </li> <li> <p><strong>Package Installation</strong>: Binary packages for Bioconductor are available when the main container <code>bioconductor_docker</code> is used ( image tag <code>>= RELEASE_3_14</code>). These binary packages do not require compilation and install 7x-8x faster than regular package installation.</p> </li> </ul> <p>Our aim is to provide up-to-date containers for the current release and devel versions of Bioconductor, and some older versions. Bioconductor’s Docker images are stored in Docker Hub; the source Dockerfile(s) are on Github.</p> <p>Our release images and devel images are based on the <a href="https://www.rocker-project.org/">Rocker Project</a> - <a href="https://github.com/rocker-org/rocker/tree/master/rstudio">rocker/rstudio</a> image and built when a Bioconductor release occurs.</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 (<em>malbec2</em>) 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>Bioconductor’s Docker images are stored in <a href="https://hub.docker.com/u/bioconductor/">Docker Hub</a>; the source Dockerfile(s) are in <a href="https://github.com/Bioconductor/bioconductor_docker">Github</a>.</p> <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> <p><strong>Note:</strong> that you may need to prepend <code>sudo</code> to all <code>docker</code> commands. But try them without first.</p> <p><strong>Prerequisites</strong>: On Linux, you need Docker <a href="https://docs.docker.com/installation/">installed</a> and on <a href="http://docs.docker.com/installation/mac/">Mac</a> or <a href="http://docs.docker.com/installation/windows/">Windows</a> you need Docker Toolbox installed and running.</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-the-container">Running the 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="get-a-copy-of-public-docker-image">Get a copy of public docker image</h5> <pre><code>docker pull bioconductor/bioconductor_docker:devel </code></pre> <h5 id="to-run-rstudio-server">To run RStudio Server:</h5> <pre><code>docker run -e PASSWORD=<password> \ -p 8787:8787 \ bioconductor/bioconductor_docker:devel </code></pre> <p>You can then open a web browser pointing to your docker host on port 8787. If you’re on Linux and using default settings, the docker host is <code>127.0.0.1</code> (or <code>localhost</code>, so the full URL to RStudio would be <code>http://localhost:8787)</code>. If you are on Mac or Windows and running <code>Docker Toolbox</code>, you can determine the docker host with the <code>docker-machine ip default</code> command.</p> <p>In the above command, <code>-e PASSWORD=</code> is setting the RStudio password and is required by the RStudio Docker image. It can be whatever you like except it cannot be <code>rstudio</code>. Log in to RStudio with the username <code>rstudio</code> and whatever password was specified.</p> <p>If you want to run RStudio as a user on your host machine, in order to read/write files in a host directory, please <a href="https://github.com/rocker-org/rocker/wiki/Sharing-files-with-host-machine">read this</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 RELEASE 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>: The <code>docker run</code> command is very powerful and versatile. For full documentation, type <code>docker run --help</code> or visit the <a href="https://docs.docker.com/reference/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>One such option for <code>docker run</code> is <code>-v</code> to mount an additional volume to the docker image. This might be useful for say mounting a local R install directory for use on the docker. The path on the docker image that should be mapped to a local R library directory is <code>/usr/local/lib/R/host-site-library</code>.</p> <p>The follow example would mount my locally installed packages to this docker directory. In turn, that path is automatically loaded in the R <code>.libPaths</code> on the docker image and all of my locally installed package would be available for use.</p> <ul> <li> <p>Running it interactively,</p> <pre><code>docker run \ -v /home/my-devel-library:/usr/local/lib/R/host-site-library \ -it \ --user rstudio \ bioconductor/bioconductor_docker:devel </code></pre> <p>without the <code>--user rstudio</code> option, the container is started and logged in as the <code>root</code> user.</p> <p>The <code>-it</code> flag gives you an interactive tty (shell/terminal) to the docker container.</p> </li> <li> <p>Running it with RStudio interface</p> <pre><code>docker run \ -v /home/my-devel-library:/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>To run the docker-compose file <code>docker-compose.yaml</code> from the same directory,</p> <pre><code>docker-compose up </code></pre> <p>Using <code>docker-compose</code>, the user can launch the image with a single command. The RStudio image is launched at <code>http://localhost:8787</code>.</p> <p>The <code>docker-composer.yaml</code> includes settings so that the user doesn’t have to worry about setting the port, password (default is <code>bioc</code>), or the volume to save libraries.</p> <p>The library path, where all the packages are installed are automatically configured to use the volume <code>$HOME/R/bioconductor_docker/<bioconductor_version></code>, in the case of the Bioconductor version 3.13, it would be <code>$HOME/R/bioconductor_docker/3.13</code>. This location is mounted on to the path, <code>/usr/local/lib/R/host-site-library</code>, which is the first value in your search path for packages if you check <code>.libPaths()</code>.</p> <p>When the user starts the docker image using <code>docker-compose</code>, it will recognize previously mounted libraries with the apprpriate bioconductor version, and save users time reinstalling the previously installed packages.</p> <p>To add another volume for data, it’s possible to modify the <code>docker-compose.yml</code> to include another volume, so all the data is stored in the same location as well.</p> <pre><code>volumes: - ${HOME}/R/bioconductor_docker/3.13:/usr/local/lib/R/host-site-library - ${HOME}/R/data:/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 a detached state, the <code>container-name</code> can be used to exec into the terminal if the user wishes <code>root</code> access in a terminal, without using RStudio.</p> <p>Within the <code>root</code> user, additional system dependencies can be installed to make the image fit the needs of the user.</p> <pre><code>docker exec -it bioc-3.13 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-containers">Modifying Containers</h2> <p>There are two ways to modify these 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 Dockerfile to declare the changes you want to make.</p> </li> </ol> <p>The second way is the recommended way. Both ways are <a href="https://docs.docker.com/userguide/dockerimages/#creating-our-own-images">documented here</a>.</p> <p>Example 1:</p> <p>My goal is to add a python package ‘tensorflow’ and to install a Bioconductor package called ‘scAlign’ on top of the base docker image i.e bioconductor/bioconductor_docker:devel.</p> <p>As a first step, my Dockerfile should inherit from the <code>bioconductor/bioconductor_docker:devel</code> image, and build from there. Since all docker images are Linux environments, and this container is specifically ‘Debian’, I need some knowledge on how to install libraries on Linux machines.</p> <p>In your new <code>Dockerfile</code>, you can have 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>This <code>Dockerfile</code> can be built with the command, (note: you can name it however you want)</p> <pre><code>docker build -t bioconductor_docker_tensorflow:devel . </code></pre> <p>This will let you use the docker image with ‘tensorflow’ installed and also <code>scAlign</code> package.</p> <pre><code>docker run -p 8787:8787 -e PASSWORD=bioc bioconductor_docker_tensorflow:devel </code></pre> <p>Example 2:</p> <p>My goal is to add all the required infrastructure to be able to compile vignettes and knit documents into pdf files. My <code>Dockerfile</code> will look like the following for this requirement,</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>This <code>Dockerfile</code> can be built with the command,</p> <pre><code>docker build -t bioconductor_docker_latex:devel . </code></pre> <p>This will let you use the docker image as needed to build and compile vignettes for packages.</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 now available for Bioconductor containers now for image tags <code>>= RELEASE_3_14</code>. This means that for all images over <code>RELEASE_3_14</code> Bioconductor packages do not need to be compiled, and a package installation using <code>BiocManager::install()</code>.</p> <p>The binary package installation provides a 7x-8x speed up as it removes the burden of compilation on the container.</p> <p>For example:</p> <pre><code>## Install binary packages on a container BiocManager::install(c('Rhtslib','SingleCellExperiment')) </code></pre> <p>Keep in mind that the container needs to be the <code>bioconductor/bioconductor_docker</code> image or a derived image. To learn how to build your own derived images, look at the section to <code>Modifying Conatiners</code></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>The latest <code>bioconductor/bioconductor_docker</code> images are available on Singularity Hub as well. Singularity is a container runtime just like Docker, and Singularity Hub is the host registry for Singularity containers.</p> <p>You can find the Singularity containers collection on this link https://singularity-hub.org/collections/3955.</p> <p>These images are particularly useful on compute clusters where you don’t need admin access. You need to have the module <code>singularity</code> installed. See https://singularity.lbl.gov/docs-installation (contact your IT department when in doubt).</p> <p>If you have Singularity installed on your machine or cluster are:</p> <p>Inspect available modules</p> <pre><code>module available </code></pre> <p>If Singularity is available,</p> <pre><code>module load singularity </code></pre> <p>Please check this link for specific usage instructions relevant to Singularity containers and their usage https://www.rocker-project.org/use/singularity/.</p> <p><a name="msft"></a></p> <h2 id="microsoft-azure-container-instances">Microsoft Azure Container Instances</h2> <p>If you are a Microsoft Azure user, you have an option to run your containers using images hosted on <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>You can learn more about the <code>bioconductor_docker</code> image hosted on Micosoft Container Registry <a href="https://hub.docker.com/_/microsoft-bioconductor/">here</a>.</p> <p>Pull the <code>bioconductor_docker</code> image from Microsoft Container Registry, specifying your <code>tag</code> of choice. Check <a href="https://hub.docker.com/_/microsoft-bioconductor-bioconductor-docker">here</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> <p><strong>Example: Run RStudio interactively from your docker container</strong></p> <p>To run RStudio in a web browser session, run the following and access it from <code>127.0.0.1:8787</code>. The default user name is “rstudio” and you can specify your password as the example below (here, it is set to ‘bioc’):</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 RStudio on your 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 or ACI</a> provide a way to run Docker containers on-demand in a managed, serverless Azure environment. To learn more, check out the documentation <a href="https://docs.microsoft.com/en-us/azure/container-instances/container-instances-overview">here</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://docs.microsoft.com/en-us/azure/guides/developer/azure-developer-guide#understanding-accounts-subscriptions-and-billing">An Azure account and a subscription</a> you can create resources in</p> </li> <li> <p><a href="https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest">Azure CLI</a></p> </li> <li> <p>Create a <a href="https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal">resource group</a> within your subscription</p> </li> </ol> <p>You can run <a href="https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest">Azure CLI or “az cli” commands</a> to create, stop, restart or delete container instances running any bioconductor image - either official images by bioconductor or images available on <a href="https://hub.docker.com/_/microsoft-bioconductor">Microsoft Container Registry</a>. To get started, ensure you have an Azure account and a subscription or <a href="https://azure.microsoft.com/en-us/free/">create a free account</a>.</p> <p>Follow <a href="https://docs.microsoft.com/en-us/azure/container-instances/container-instances-quickstart">this tutorial</a> to get familiar with Azure Container Instances.</p> <p>To run the bioconductor image hosted on Microsoft Container Registry or MCR, create a new resource group in your Azure subscription. Then run the following command using Azure CLI. You can customize any or all of the inputs. This command is adapted to run on an Ubuntu machine:</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” (similar to the official bioconductor docker image). Here we set the password for RStudio to ‘bioc’ in the environment variable configuration. The <code>--cpu</code> and <code>--memory</code> (in GB) configurations can also be customized to your needs. By default, ACI have 1 cpu core and 1.5GB of memory assigned.</p> <p>To learn more about what you can configure and customize when creating an 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 ensure that the data persists between different analysis sessions when using Azure Container Instances, you can use the feature to <a href="https://docs.microsoft.com/en-us/azure/container-instances/container-instances-volume-azure-files">mount Azure file share to your container instance</a>. In this example, we will create an ACI that mounts the “/home/rstudio” directory in RStudio to an <a href="https://docs.microsoft.com/en-us/azure/storage/files/storage-files-introduction">Azure File Share</a>.</p> <p><strong>Prerequisites</strong>:</p> <ol> <li> <p><a href="https://docs.microsoft.com/en-us/azure/guides/developer/azure-developer-guide#understanding-accounts-subscriptions-and-billing">An Azure account and a subscription</a> you can create resources in</p> </li> <li> <p><a href="https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest">Azure CLI</a></p> </li> <li> <p>Create a <a href="https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal">resource group</a> within your subscription</p> </li> </ol> <p>Now, run the following Azure CLI commands to:</p> <ol> <li> <p>Create an <a href="https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-cli">Azure Storage</a> account</p> </li> <li> <p>Create an <a href="https://docs.microsoft.com/en-us/azure/storage/files/storage-how-to-use-files-cli">Azure file share</a></p> </li> <li> <p>Get the <a href="https://docs.microsoft.com/en-us/cli/azure/storage/account/keys?view=azure-cli-latest">storage account key</a></p> </li> </ol> <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>Here is an example command to mount an Azure file share to an ACI running bioconductor. This command is adapted to run on an Ubuntu machine:</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>Here we expose port 8787 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” (similar to the official bioconductor docker image). Here we set the password for RStudio to ‘bioc’ in the environment variable configuration. The “–cpu” and “–memory” (in GB) configurations can also be customized to your needs. By default, ACI have 1 cpu core and 1.5GB of memory assigned. Here, we also mount RStudio “/home/rstudio” directory to a persistent Azure file share named “fileShareName” in the storage account specified. When you stop or restart an 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://docs.microsoft.com/en-us/azure/container-instances/container-instances-stop-start">stop, start, restart</a> or <a href="https://docs.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 <a href="https://docs.microsoft.com/en-us/cli/azure/container?view=azure-cli-latest#commands">here</a>.</p> <p>Replace <code>containerName</code> and <code>resourceGroupName</code> in the following CLI commands.</p> <h5 id="stop-the-container-instance">Stop the container instance</h5> <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>To not be prompted for confirmation for deleting the ACI:</p> <pre><code>az container delete -n containerName -g resourceGroupName -y </code></pre> <p>To troubleshoot any issues when using Azure Container Instances, try out the recommendations <a href="https://docs.microsoft.com/en-us/azure/container-instances/container-instances-troubleshooting">here</a>. For feedback or further issues, contact us via <a href="mailto:genomics@microsoft.com">email</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 <a href="https://github.com/Bioconductor/bioconductor_docker/blob/master/best_practices.md">here</a>.</p> <p>link: https://github.com/Bioconductor/bioconductor_docker/blob/master/best_practices.md</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 images. These images were maintained by Bioconductor Core, and also the community.</p> <p><a name="legacy"></a></p> <h3 id="legacy-containers">Legacy Containers</h3> <p>These images are NO LONGER MAINTAINED and updated. They will however be available to use should a user choose. They are not supported anymore by the Bioconductor Core team.</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> makes it possible to easily install any package the user chooses since all the system dependencies are built in to this new image. The previous images did not have all the system dependencies built in to the image. The new installation of packages can be done with,</p> <pre><code>BiocManager::install(c("package_name", "package_name")) </code></pre> <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>Hard to extend because there were multiple flavors of images.</p> </li> <li> <p>Naming convention was making things harder to use.</p> </li> <li> <p>Images which were not maintained were not deprecated.</p> </li> </ul> <p><a name="issues"></a></p> <h3 id="reporting-issues">Reporting Issues</h3> <p>Please report issues with the new set of images on <a href="https://github.com/Bioconductor/bioconductor_docker/issues">GitHub Issues</a> or the <a href="mailto:bioc-devel@r-project.org">Bioc-devel</a> mailing list.</p> <p>These issues can be questions about anything related to this piece of software such as, usage, extending Docker images, enhancements, and bug reports.</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 - 2024 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>