10383: Merge branch 'master' into 10383-arv-put-incremental-upload

[arvados.git] / doc / user / topics / arv-docker.html.textile.liquid

diff --git a/doc/user/topics/arv-docker.html.textile.liquid b/doc/user/topics/arv-docker.html.textile.liquid
index 46e220f13a13cc47b4b89ec9efdd40bae45726c2..1a31d126da698495eca853b72e1dcca9424c94a1 100644 (file)
--- a/doc/user/topics/arv-docker.html.textile.liquid
+++ b/doc/user/topics/arv-docker.html.textile.liquid
@@ -1,27 +1,31 @@
 ---
 layout: default
 navsection: userguide
-title: "Customizing the Crunch runtime environment"
+title: "Customizing Crunch environment using Docker"
 ...
 
-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/
+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/
 
-This page will demonstrate:
+This page will demonstrate how to:
 
-# How to fetch the arvados/jobs Docker image
+# Fetch the arvados/jobs Docker image
 # Manually install additional software into the container
 # Create a new custom image
-# Upload that image to Arvados for use by Crunch jobs.
+# Upload that image to Arvados for use by Crunch jobs
+# Share your image with others
 
+{% include 'tutorial_expectations_workstation' %}
 
-{% include 'tutorial_expectations' %}
+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.
 
-h2. Fetching a starting image
+h2. Fetch a starting image
 
-First, download the latest image from the Docker registry:
+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.
+
+Download the latest "arvados/jobs" image from the Docker registry:
 
 <notextile>
-<pre><code>$ <span class="userinput">docker pull arvados/jobs</span>
+<pre><code>$ <span class="userinput">docker pull arvados/jobs:latest</span>
 Pulling repository arvados/jobs
 3132168f2acb: Download complete
 a42b7f2c59b6: Download complete
@@ -41,9 +45,9 @@ c7fd77eedb96: Download complete
 </code></pre>
 </notextile>
 
-h2. Installing new packages
+h2. Install new packages
 
-Next, enter the container using "docker run", the arvados/jobs image, and the program you want to run (in this case the bash shell).
+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).
 
 <notextile>
 <pre><code>$ <span class="userinput">docker run --interactive --tty --user root arvados/jobs /bin/bash</span>
@@ -148,7 +152,7 @@ Type 'q()' to quit R.
 </code></pre>
 </notextile>
 
-Note that you are not limited to installing Debian packages.  You may compile C 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.
+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.
 
 h2. Create a new image
 
@@ -185,3 +189,14 @@ You are now able to specify the runtime environment for your program using the @
 <notextile>
 {% code 'example_docker' as javascript %}
 </notextile>
+
+* The @docker_image@ field can be one of: the Docker repository name (as shown above), the Docker image hash, or the Arvados collection portable data hash.
+
+h2. Share Docker images
+
+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.
+
+<notextile>
+<pre><code>$ <span class="userinput">arv keep docker --project-uuid qr1hi-j7d0g-xxxxxxxxxxxxxxx arvados/jobs-with-r</span>
+</code></pre>
+</notextile>