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

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Customizing Crunch environment using Docker"
   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 customize the runtime environment (e.g., the programs, libraries, and other dependencies needed to run a job) that a crunch script 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 demonstrate how to:
  15
  16 # Fetch the arvados/jobs Docker image
  17 # Manually install additional software into the container
  18 # Create a new custom image
  19 # Upload that image to Arvados for use by Crunch jobs
  20 # Share your image with others
  21
  22 {% include 'tutorial_expectations_workstation' %}
  23
  24 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.
  25
  26 h2. Fetch a starting image
  27
  28 The easiest way to begin is to start from the "arvados/jobs" image which already has the Arvados SDK installed along with other configuration required for use with Crunch.
  29
  30 Download the latest "arvados/jobs" image from the Docker registry:
  31
  32 <notextile>
  33 <pre><code>$ <span class="userinput">docker pull arvados/jobs:latest</span>
  34 Pulling repository arvados/jobs
  35 3132168f2acb: Download complete
  36 a42b7f2c59b6: Download complete
  37 e5afdf26a7ae: Download complete
  38 5cae48636278: Download complete
  39 7a4f91b70558: Download complete
  40 a04a275c1fd6: Download complete
  41 c433ff206a22: Download complete
  42 b2e539b45f96: Download complete
  43 073b2581c6be: Download complete
  44 593915af19dc: Download complete
  45 32260b35005e: Download complete
  46 6e5b860c1cde: Download complete
  47 95f0bfb43d4d: Download complete
  48 c7fd77eedb96: Download complete
  49 0d7685aafd00: Download complete
  50 </code></pre>
  51 </notextile>
  52
  53 h2. Install new packages
  54
  55 Next, enter the container using @docker run@, providing the arvados/jobs image and the program you want to run (in this case the bash shell).
  56
  57 <notextile>
  58 <pre><code>$ <span class="userinput">docker run --interactive --tty --user root arvados/jobs /bin/bash</span>
  59 root@fbf1d0f529d5:/#
  60 </code></pre>
  61 </notextile>
  62
  63 Next, update the package list using @apt-get update@.
  64
  65 <notextile>
  66 <pre><code>root@fbf1d0f529d5:/# apt-get update
  67 Hit http://security.debian.org jessie/updates InRelease
  68 Ign http://httpredir.debian.org jessie InRelease
  69 Ign http://apt.arvados.org jessie InRelease
  70 Hit http://apt.arvados.org jessie Release.gpg
  71 Get:1 http://security.debian.org jessie/updates/main amd64 Packages [431 kB]
  72 Hit http://apt.arvados.org jessie Release
  73 Hit http://httpredir.debian.org jessie-updates InRelease
  74 Get:2 http://apt.arvados.org jessie/main amd64 Packages [257 kB]
  75 Get:3 http://httpredir.debian.org jessie-updates/main amd64 Packages [17.6 kB]
  76 Hit http://httpredir.debian.org jessie Release.gpg
  77 Hit http://httpredir.debian.org jessie Release
  78 Get:4 http://httpredir.debian.org jessie/main amd64 Packages [9049 kB]
  79 Fetched 9755 kB in 2s (3894 kB/s)
  80 Reading package lists... Done
  81 </code></pre>
  82 </notextile>
  83
  84 In this example, we will install the "R" statistical language Debian package "r-base-core".  Use @apt-get install@:
  85
  86 <notextile>
  87 <pre><code>root@fbf1d0f529d5:/# <span class="userinput">apt-get install r-base-core</span>
  88 Reading package lists... Done
  89 Building dependency tree
  90 Reading state information... Done
  91 The following extra packages will be installed:
  92   [...]
  93   libxxf86vm1 make patch r-base-core r-base-dev r-cran-boot r-cran-class
  94   r-cran-cluster r-cran-codetools r-cran-foreign r-cran-kernsmooth
  95   r-cran-lattice r-cran-mass r-cran-matrix r-cran-mgcv r-cran-nlme r-cran-nnet
  96   r-cran-rpart r-cran-spatial r-cran-survival r-doc-html r-recommended
  97   [...]
  98 Suggested packages:
  99   [...]
 100 The following NEW packages will be installed:
 101   [...]
 102   libxxf86vm1 make patch r-base-core r-base-dev r-cran-boot r-cran-class
 103   r-cran-cluster r-cran-codetools r-cran-foreign r-cran-kernsmooth
 104   r-cran-lattice r-cran-mass r-cran-matrix r-cran-mgcv r-cran-nlme r-cran-nnet
 105   r-cran-rpart r-cran-spatial r-cran-survival r-doc-html r-recommended
 106   [...]
 107 0 upgraded, 203 newly installed, 0 to remove and 39 not upgraded.
 108 Need to get 124 MB of archives.
 109 After this operation, 334 MB of additional disk space will be used.
 110 Do you want to continue [Y/n]? y
 111 [...]
 112 Get:130 http://httpredir.debian.org/debian/ jessie/main r-cran-cluster amd64 1.15.3-1 [475 kB]
 113 Get:131 http://httpredir.debian.org/debian/ jessie/main r-base-dev all 3.1.1-1 [4018 B]
 114 Get:132 http://httpredir.debian.org/debian/ jessie/main r-cran-boot all 1.3-13-1 [571 kB]
 115 Get:133 http://httpredir.debian.org/debian/ jessie/main r-cran-codetools all 0.2-9-1 [45.7 kB]
 116 Get:134 http://httpredir.debian.org/debian/ jessie/main r-cran-rpart amd64 4.1-8-1 [862 kB]
 117 Get:135 http://httpredir.debian.org/debian/ jessie/main r-cran-foreign amd64 0.8.61-1 [213 kB]
 118 [...]
 119 Fetched 124 MB in 52s (2380 kB/s)
 120 debconf: delaying package configuration, since apt-utils is not installed
 121 [...]
 122 Unpacking r-base-core (3.1.1-1+b2) ...
 123 Selecting previously unselected package r-base-dev.
 124 Preparing to unpack .../r-base-dev_3.1.1-1_all.deb ...
 125 Unpacking r-base-dev (3.1.1-1) ...
 126 Selecting previously unselected package r-cran-boot.
 127 Preparing to unpack .../r-cran-boot_1.3-13-1_all.deb ...
 128 Unpacking r-cran-boot (1.3-13-1) ...
 129 Selecting previously unselected package r-cran-mass.
 130 [...]
 131 Setting up r-base-core (3.1.1-1+b2) ...
 132
 133 Creating config file /etc/R/Renviron with new version
 134 Setting up r-base-dev (3.1.1-1) ...
 135 Setting up r-cran-boot (1.3-13-1) ...
 136 Setting up r-cran-mass (7.3-34-1) ...
 137 Setting up r-cran-class (7.3-11-1) ...
 138 [...]
 139 </code></pre>
 140 </notextile>
 141
 142 Now we can verify that "R" is installed:
 143
 144 <notextile>
 145 <pre><code>root@fbf1d0f529d5:/# <span class="userinput">R</span>
 146
 147 R version 3.1.1 (2014-07-10) -- "Sock it to Me"
 148 Copyright (C) 2014 The R Foundation for Statistical Computing
 149 Platform: x86_64-pc-linux-gnu (64-bit)
 150
 151 R is free software and comes with ABSOLUTELY NO WARRANTY.
 152 You are welcome to redistribute it under certain conditions.
 153 Type 'license()' or 'licence()' for distribution details.
 154
 155 R is a collaborative project with many contributors.
 156 Type 'contributors()' for more information and
 157 'citation()' on how to cite R or R packages in publications.
 158
 159 Type 'demo()' for some demos, 'help()' for on-line help, or
 160 'help.start()' for an HTML browser interface to help.
 161 Type 'q()' to quit R.
 162
 163 >
 164 </code></pre>
 165 </notextile>
 166
 167 Note that 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.
 168
 169 h2. Create a new image
 170
 171 We're now ready to create a new Docker image.  First, quit the container, then use @docker commit@ to create a new image from the stopped container.  The container id can be found in the default hostname of the container displayed in the prompt, in this case @fbf1d0f529d5@:
 172
 173 <notextile>
 174 <pre><code>root@fbf1d0f529d5:/# <span class="userinput">exit</span>
 175 $ <span class="userinput">docker commit fbf1d0f529d5 arvados/jobs-with-r</span>
 176 sha256:2818853ff9f9af5d7f77979803baac9c4710790ad2b84c1a754b02728fdff205
 177 $ <span class="userinput">docker images</span>
 178 $ docker images |head
 179 REPOSITORY            TAG                 IMAGE ID            CREATED             SIZE
 180 arvados/jobs-with-r   latest              2818853ff9f9        9 seconds ago       703.1 MB
 181 arvados/jobs          latest              12b9f859d48c        4 days ago          362 MB
 182 </code></pre>
 183 </notextile>
 184
 185 h2. Upload your image
 186
 187 Finally, we are ready to upload the new Docker image to Arvados.  Use @arv keep docker@ with the image repository name to upload the image.  Without arguments, @arv keep docker@ will print out the list of Docker images in Arvados that are available to you.
 188
 189 <notextile>
 190 <pre><code>$ <span class="userinput">arv keep docker arvados/jobs-with-r</span>
 191 703M / 703M 100.0%
 192 Collection saved as 'Docker image arvados/jobs-with-r:latest 2818853ff9f9'
 193 qr1hi-4zz18-abcdefghijklmno
 194 $ <span class="userinput">arv keep docker</span>
 195 REPOSITORY                      TAG         IMAGE ID      COLLECTION                     CREATED
 196 arvados/jobs-with-r             latest      2818853ff9f9  qr1hi-4zz18-abcdefghijklmno    Tue Jan 17 20:35:53 2017
 197 </code></pre>
 198 </notextile>
 199
 200 You are now able to specify the runtime environment for your program using @DockerRequirement@ in your workflow:
 201
 202 <pre>
 203 hints:
 204   DockerRequirement:
 205     dockerPull: arvados/jobs-with-r
 206 </pre>
 207
 208 h2. Share Docker images
 209
 210 Docker images are subject to normal Arvados permissions.  If wish to share your Docker image with others (or wish to share a pipeline template that uses your Docker image) you will need to use @arv keep docker@ with the @--project-uuid@ option to upload the image to a shared project.
 211
 212 <notextile>
 213 <pre><code>$ <span class="userinput">arv keep docker --project-uuid qr1hi-j7d0g-xxxxxxxxxxxxxxx arvados/jobs-with-r</span>
 214 </code></pre>
 215 </notextile>