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' %}
  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</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@a0e8299b59aa:/#
  55 </code></pre>
  56 </notextile>
  57
  58 Next, update the package list using @apt-get update@.
  59
  60 <notextile>
  61 <pre><code>root@a0e8299b59aa:/# <span class="userinput">apt-get update</span>
  62 Get:1 http://apt.arvados.org wheezy Release.gpg [490 B]
  63 Get:2 http://apt.arvados.org wheezy Release [1568 B]
  64 Get:3 http://apt.arvados.org wheezy/main amd64 Packages [34.6 kB]
  65 Get:4 http://ftp.us.debian.org wheezy Release.gpg [1655 B]
  66 Get:5 http://ftp.us.debian.org wheezy-updates Release.gpg [836 B]
  67 Get:6 http://ftp.us.debian.org wheezy Release [168 kB]
  68 Ign http://apt.arvados.org wheezy/main Translation-en
  69 Get:7 http://security.debian.org wheezy/updates Release.gpg [836 B]
  70 Get:8 http://security.debian.org wheezy/updates Release [102 kB]
  71 Get:9 http://ftp.us.debian.org wheezy-updates Release [124 kB]
  72 Get:10 http://ftp.us.debian.org wheezy/main amd64 Packages [5841 kB]
  73 Get:11 http://security.debian.org wheezy/updates/main amd64 Packages [218 kB]
  74 Get:12 http://security.debian.org wheezy/updates/main Translation-en [123 kB]
  75 Hit http://ftp.us.debian.org wheezy/main Translation-en
  76 Hit http://ftp.us.debian.org wheezy-updates/main amd64 Packages/DiffIndex
  77 Hit http://ftp.us.debian.org wheezy-updates/main Translation-en/DiffIndex
  78 Fetched 6617 kB in 5s (1209 kB/s)
  79 Reading package lists... Done
  80 </code></pre>
  81 </notextile>
  82
  83 In this example, we will install the "R" statistical language Debian package "r-base-core".  Use @apt-get install@:
  84
  85 <notextile>
  86 <pre><code>root@a0e8299b59aa:/# <span class="userinput">apt-get install r-base-core</span>
  87 Reading package lists... Done
  88 Building dependency tree
  89 Reading state information... Done
  90 The following extra packages will be installed:
  91   [...]
  92 libxv1 libxxf86dga1 libxxf86vm1 r-base-core r-base-dev r-base-html r-cran-boot r-cran-class r-cran-cluster r-cran-codetools
  93   [...]
  94 Suggested packages:
  95   [...]
  96 The following NEW packages will be installed:
  97   [...]
  98   libxv1 libxxf86dga1 libxxf86vm1 r-base r-base-core r-base-dev r-base-html r-cran-boot r-cran-class r-cran-cluster
  99   [...]
 100 0 upgraded, 107 newly installed, 0 to remove and 9 not upgraded.
 101 Need to get 88.2 MB of archives.
 102 After this operation, 219 MB of additional disk space will be used.
 103 Do you want to continue [Y/n]? y
 104 [...]
 105 Get:85 http://ftp.us.debian.org/debian/ wheezy/main r-base-core amd64 2.15.1-4 [20.6 MB]
 106 Get:86 http://ftp.us.debian.org/debian/ wheezy/main r-base-dev all 2.15.1-4 [3882 B]
 107 Get:87 http://ftp.us.debian.org/debian/ wheezy/main r-cran-boot all 1.3-5-1 [472 kB]
 108 [...]
 109 Fetched 88.2 MB in 2min 17s (642 kB/s)
 110 Extracting templates from packages: 100%
 111 Preconfiguring packages ...
 112 [...]
 113 Unpacking r-base-core (from .../r-base-core_2.15.1-4_amd64.deb) ...
 114 Selecting previously unselected package r-base-dev.
 115 Unpacking r-base-dev (from .../r-base-dev_2.15.1-4_all.deb) ...
 116 Selecting previously unselected package r-cran-boot.
 117 Unpacking r-cran-boot (from .../r-cran-boot_1.3-5-1_all.deb) ...
 118 [...]
 119 Setting up r-base-core (2.15.1-4) ...
 120 Setting R_PAPERSIZE_USER default to 'a4'
 121
 122 Creating config file /etc/R/Renviron with new version
 123 Setting up r-base-dev (2.15.1-4) ...
 124 Setting up r-cran-boot (1.3-5-1) ...
 125 [...]
 126 </code></pre>
 127 </notextile>
 128
 129 Now we can verify that "R" is installed:
 130
 131 <notextile>
 132 <pre><code>root@a0e8299b59aa:/# <span class="userinput">R</span>
 133
 134 R version 2.15.1 (2012-06-22) -- "Roasted Marshmallows"
 135 Copyright (C) 2012 The R Foundation for Statistical Computing
 136 ISBN 3-900051-07-0
 137 Platform: x86_64-pc-linux-gnu (64-bit)
 138
 139 R is free software and comes with ABSOLUTELY NO WARRANTY.
 140 You are welcome to redistribute it under certain conditions.
 141 Type 'license()' or 'licence()' for distribution details.
 142
 143 R is a collaborative project with many contributors.
 144 Type 'contributors()' for more information and
 145 'citation()' on how to cite R or R packages in publications.
 146
 147 Type 'demo()' for some demos, 'help()' for on-line help, or
 148 'help.start()' for an HTML browser interface to help.
 149 Type 'q()' to quit R.
 150
 151 >
 152 </code></pre>
 153 </notextile>
 154
 155 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.
 156
 157 h2. Create a new image
 158
 159 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 @a0e8299b59aa@:
 160
 161 <notextile>
 162 <pre><code>root@a0e8299b59aa:/# <span class="userinput">exit</span>
 163 $ <span class="userinput">docker commit a0e8299b59aa arvados/jobs-with-r</span>
 164 33ea6b87792364cb9989a149c36a31e5a9c8cf96694ba05f66545ad7b842522e
 165 $ <span class="userinput">docker images</span>
 166 REPOSITORY            TAG                 IMAGE ID            CREATED              VIRTUAL SIZE
 167 arvados/jobs-with-r   latest              33ea6b877923        43 seconds ago       1.607 GB
 168 arvados/jobs          latest              3132168f2acb        22 hours ago         1.314 GB
 169 </code></pre>
 170 </notextile>
 171
 172 h2. Upload your image
 173
 174 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.
 175
 176 <notextile>
 177 <pre><code>$ <span class="userinput">arv keep docker arvados/jobs-with-r</span>
 178 1591M / 1591M 100.0%
 179 Collection saved as 'Docker image arvados/jobs-with-r:latest 33ea6b877923'
 180 qr1hi-4zz18-3fk2px2ji25nst2
 181 $ <span class="userinput">arv keep docker</span>
 182 REPOSITORY                      TAG         IMAGE ID      COLLECTION                     CREATED
 183 arvados/jobs-with-r             latest      33ea6b877923  qr1hi-4zz18-3fk2px2ji25nst2    Thu Oct 16 13:58:53 2014
 184 </code></pre>
 185 </notextile>
 186
 187 You are now able to specify the runtime environment for your program using the @docker_image@ field of the @runtime_constaints@ section of your pipeline components:
 188
 189 <notextile>
 190 {% code 'example_docker' as javascript %}
 191 </notextile>
 192
 193 * The @docker_image@ field can be one of: the Docker repository name (as shown above), the Docker image hash, the Arvados collection UUID, or the Arvados collection portable data hash.
 194
 195 h2. Share Docker images
 196
 197 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.
 198
 199 <notextile>
 200 <pre><code>$ <span class="userinput">arv keep docker --project-uuid zzzzz-j7d0g-u7zg1qdaowykd8d arvados/jobs-with-r</span>
 201 </code></pre>
 202 </notextile>