X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/337b055122485e669cc601c91a78f8fdd2625b3e..125dd3b1e5f34156b002951f504f5346cc5d7e8d:/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 f039a6c3e8..391b4e779d 100644
--- a/doc/user/topics/arv-docker.html.textile.liquid
+++ b/doc/user/topics/arv-docker.html.textile.liquid
@@ -1,7 +1,7 @@
 ---
 layout: default
 navsection: userguide
-title: "Working with Docker images"
+title: "Working with container images"
 ...
 {% comment %}
 Copyright (C) The Arvados Authors. All rights reserved.
@@ -9,34 +9,34 @@ Copyright (C) The Arvados Authors. All rights reserved.
 SPDX-License-Identifier: CC-BY-SA-3.0
 {% endcomment %}
 
-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/
+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/ or "Singularity":https://sylabs.io/singularity/.  Docker and Singularity are tools for building and running containers that isolate applications from other applications running on the same node.  For detailed information, see the "Docker User Guide":https://docs.docker.com/userguide/ and the "Introduction to Singularity":https://sylabs.io/guides/3.5/user-guide/introduction.html.
 
-This page will describe:
+Note that Arvados always works with Docker images, even when it is configured to use Singularity to run containers. There are some differences between the two runtimes that can affect your containers. See the "Singularity architecture":{{site.baseurl}}/architecture/singularity.html page for details.
 
-# Create a custom image using a Dockerfile
-# Uploading an image to Arvados
-# Sources of pre-built bioinformatics Docker images
+This page describes:
+
+# "Create a custom image using a Dockerfile":#create
+# "Uploading an image to Arvados":#upload
+# "Sources of pre-built bioinformatics Docker images":#sources
 
 {% include 'tutorial_expectations_workstation' %}
 
-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.
+You also need to 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. Create a custom image using a Dockerfile
+h2(#create). Create a custom image using a Dockerfile
 
 This example shows how to create a Docker image and add the R package.
 
 First, create new directory called @docker-example@, in that directory create a file called @Dockerfile@.
 
 <notextile>
-<pre><code>
-$ mkdir docker-example-r-base
-$ cd docker-example-r-base
+<pre><code>$ <span class="userinput">mkdir docker-example-r-base</span>
+$ <span class="userinput">cd docker-example-r-base</span>
 </code></pre>
 </notextile>
 
 <notextile>
-<pre><code>
-FROM ubuntu:bionic
+<pre><code>FROM ubuntu:bionic
 RUN apt-get update && apt-get -yq --no-install-recommends install r-base-core
 </code></pre>
 </notextile>
@@ -45,13 +45,14 @@ The "RUN" command is executed inside the container and can be any shell command
 
 You can also visit the "Docker tutorial":https://docs.docker.com/get-started/part2/ for more information and examples.
 
+You should add your Dockerfiles to the same source control repository as the Workflows that use them.
+
 h3. Create a new image
 
 We're now ready to create a new Docker image.  Use @docker build@ to create a new image from the Dockerfile.
 
 <notextile>
-<pre><code>
-docker-example-r-base$ docker build -t docker-example-r-base .
+<pre><code>docker-example-r-base$ <span class="userinput">docker build -t docker-example-r-base .</span>
 </code></pre>
 </notextile>
 
@@ -60,17 +61,16 @@ h3. Verify image
 Now we can verify that "R" is installed:
 
 <notextile>
-<pre><code>$ docker run -ti docker-example-r-base
+<pre><code>$ <span class="userinput">docker run -ti docker-example-r-base</span>
 root@57ec8f8b2663:/# R
 
 R version 3.4.4 (2018-03-15) -- "Someone to Lean On"
 Copyright (C) 2018 The R Foundation for Statistical Computing
 Platform: x86_64-pc-linux-gnu (64-bit)
-
 </code></pre>
 </notextile>
 
-h2. Upload your image
+h2(#upload). Upload your image
 
 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.
 
@@ -80,11 +80,11 @@ Finally, we are ready to upload the new Docker image to Arvados.  Use @arv-keepd
 206M / 206M 100.0% 2020-06-29 13:48:21 arvados.arv_put[769] INFO:
 
 2020-06-29 13:48:21 arvados.arv_put[769] INFO: Collection saved as 'Docker image docker-example-r-base:latest sha256:edd10'
-x20vs-4zz18-0tayximqcyb6uf8
+zzzzz-4zz18-0tayximqcyb6uf8
 
 $ <span class="userinput">arv-keepdocker images</span>
 REPOSITORY                      TAG         IMAGE ID      COLLECTION                     CREATED
-docker-example-r-base           latest      sha256:edd10  x20vs-4zz18-0tayximqcyb6uf8    Mon Jun 29 17:46:16 2020
+docker-example-r-base           latest      sha256:edd10  zzzzz-4zz18-0tayximqcyb6uf8    Mon Jun 29 17:46:16 2020
 </code></pre>
 </notextile>
 
@@ -101,11 +101,11 @@ h3. Uploading Docker images to a shared project
 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.
 
 <notextile>
-<pre><code>$ <span class="userinput">arv-keepdocker docker-example-r-base --project-uuid qr1hi-j7d0g-xxxxxxxxxxxxxxx</span>
+<pre><code>$ <span class="userinput">arv-keepdocker docker-example-r-base --project-uuid zzzzz-j7d0g-xxxxxxxxxxxxxxx</span>
 </code></pre>
 </notextile>
 
-h2. Sources of pre-built images
+h2(#sources). Sources of pre-built images
 
 In addition to creating your own contianers, there are a number of resources where you can find bioinformatics tools already wrapped in container images: