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

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