doc/user/topics/arv-docker.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Working with Docker images"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 This page describes how to set up the runtime environment (e.g., the programs, libraries, and other dependencies needed to run a job) that a workflow step will be run in using "Docker.":https://www.docker.com/  Docker is a tool for building and running containers that isolate applications from other applications running on the same node.  For detailed information about Docker, see the "Docker User Guide.":https://docs.docker.com/userguide/
  13
  14 This page will describe:
  15
  16 # Create a custom image using a Dockerfile
  17 # Uploading an image to Arvados
  18 # Sources of pre-built bioinformatics Docker images
  19
  20 {% include 'tutorial_expectations_workstation' %}
  21
  22 You also need ensure that "Docker is installed,":https://docs.docker.com/installation/ the Docker daemon is running, and you have permission to access Docker.  You can test this by running @docker version@.  If you receive a permission denied error, your user account may need to be added to the @docker@ group.  If you have root access, you can add yourself to the @docker@ group using @$ sudo addgroup $USER docker@ then log out and log back in again; otherwise consult your local sysadmin.
  23
  24 h2. Create a custom image using a Dockerfile
  25
  26 This example shows how to create a Docker image and add the R package.
  27
  28 First, create new directory called @docker-example@, in that directory create a file called @Dockerfile@.
  29
  30 <notextile>
  31 <pre><code>
  32 $ mkdir docker-example-r-base
  33 $ cd docker-example-r-base
  34 </code></pre>
  35 </notextile>
  36
  37 <notextile>
  38 <pre><code>
  39 FROM ubuntu:bionic
  40 RUN apt-get update && apt-get -yq --no-install-recommends install r-base-core
  41 </code></pre>
  42 </notextile>
  43
  44 The "RUN" command is executed inside the container and can be any shell command line.  You are not limited to installing Debian packages.  You may compile programs or libraries from source and install them, edit systemwide configuration files, use other package managers such as @pip@ or @gem@, and perform any other customization necessary to run your program.
  45
  46 You can also visit the "Docker tutorial":https://docs.docker.com/get-started/part2/ for more information and examples.
  47
  48 You should add your Dockerfiles to the same source control repository as the Workflows that use them.
  49
  50 h3. Create a new image
  51
  52 We're now ready to create a new Docker image.  Use @docker build@ to create a new image from the Dockerfile.
  53
  54 <notextile>
  55 <pre><code>
  56 docker-example-r-base$ docker build -t docker-example-r-base .
  57 </code></pre>
  58 </notextile>
  59
  60 h3. Verify image
  61
  62 Now we can verify that "R" is installed:
  63
  64 <notextile>
  65 <pre><code>$ docker run -ti docker-example-r-base
  66 root@57ec8f8b2663:/# R
  67
  68 R version 3.4.4 (2018-03-15) -- "Someone to Lean On"
  69 Copyright (C) 2018 The R Foundation for Statistical Computing
  70 Platform: x86_64-pc-linux-gnu (64-bit)
  71
  72 </code></pre>
  73 </notextile>
  74
  75 h2. Upload your image
  76
  77 Finally, we are ready to upload the new Docker image to Arvados.  Use @arv-keepdocker@ with the image repository name to upload the image.  Without arguments, @arv-keepdocker@ will print out the list of Docker images in Arvados that are available to you.
  78
  79 <notextile>
  80 <pre><code>$ <span class="userinput">arv-keepdocker docker-example-r-base</span>
  81 2020-06-29 13:48:19 arvados.arv_put[769] INFO: Creating new cache file at /home/peter/.cache/arvados/arv-put/39ddb51ebf6c5fcb3d713b5969466967
  82 206M / 206M 100.0% 2020-06-29 13:48:21 arvados.arv_put[769] INFO:
  83
  84 2020-06-29 13:48:21 arvados.arv_put[769] INFO: Collection saved as 'Docker image docker-example-r-base:latest sha256:edd10'
  85 x20vs-4zz18-0tayximqcyb6uf8
  86
  87 $ <span class="userinput">arv-keepdocker images</span>
  88 REPOSITORY                      TAG         IMAGE ID      COLLECTION                     CREATED
  89 docker-example-r-base           latest      sha256:edd10  x20vs-4zz18-0tayximqcyb6uf8    Mon Jun 29 17:46:16 2020
  90 </code></pre>
  91 </notextile>
  92
  93 You are now able to specify the runtime environment for your program using @DockerRequirement@ in your workflow:
  94
  95 <pre>
  96 hints:
  97   DockerRequirement:
  98     dockerPull: docker-example-r-base
  99 </pre>
 100
 101 h3. Uploading Docker images to a shared project
 102
 103 Docker images are subject to normal Arvados permissions.  If wish to share your Docker image with others you should use @arv-keepdocker@ with the @--project-uuid@ option to add the image to a shared project and ensure that metadata is set correctly.
 104
 105 <notextile>
 106 <pre><code>$ <span class="userinput">arv-keepdocker docker-example-r-base --project-uuid zzzzz-j7d0g-xxxxxxxxxxxxxxx</span>
 107 </code></pre>
 108 </notextile>
 109
 110 h2. Sources of pre-built images
 111
 112 In addition to creating your own contianers, there are a number of resources where you can find bioinformatics tools already wrapped in container images:
 113
 114 "BioContainers":https://biocontainers.pro/
 115
 116 "Dockstore":https://dockstore.org/
 117
 118 "Docker Hub":https://hub.docker.com/