X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/4f50d3f21494a19eb073a3f8435e872321f35fb6..b4f172a329980127db895becda91543fd65b6b39:/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 d878f8bc8b..391b4e779d 100644
--- a/doc/user/topics/arv-docker.html.textile.liquid
+++ b/doc/user/topics/arv-docker.html.textile.liquid
@@ -1,20 +1,116 @@
---
layout: default
navsection: userguide
-title: "Customizing the Crunch runtime environment"
+title: "Working with container images"
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-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.
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-{% include 'tutorial_expectations' %}
+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.
-h1. Docker
+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.
-Arvados uses "Docker":https://www.docker.com/ images to provide a runtime environment for Crunch jobs.
+This page describes:
-This page will demonstrate how to build the arvados/jobs Docker image, manually install additional software into the image to create a new custom image, and upload that image to Arvados for use by Crunch jobs.
+# "Create a custom image using a Dockerfile":#create
+# "Uploading an image to Arvados":#upload
+# "Sources of pre-built bioinformatics Docker images":#sources
-Arvados images are based on "Debian.":https://debian.org In order to build
+{% include 'tutorial_expectations_workstation' %}
-cd ~/arvados/docker
-./build.sh jobs-image
+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). 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@.
+
+
+$ mkdir docker-example-r-base
+$ cd docker-example-r-base
+
+FROM ubuntu:bionic
+RUN apt-get update && apt-get -yq --no-install-recommends install r-base-core
+
+docker-example-r-base$ docker build -t docker-example-r-base .
+
+$ docker run -ti docker-example-r-base
+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)
+
+$ arv-keepdocker docker-example-r-base
+2020-06-29 13:48:19 arvados.arv_put[769] INFO: Creating new cache file at /home/peter/.cache/arvados/arv-put/39ddb51ebf6c5fcb3d713b5969466967
+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'
+zzzzz-4zz18-0tayximqcyb6uf8
+
+$ arv-keepdocker images
+REPOSITORY TAG IMAGE ID COLLECTION CREATED
+docker-example-r-base latest sha256:edd10 zzzzz-4zz18-0tayximqcyb6uf8 Mon Jun 29 17:46:16 2020
+
+hints: + DockerRequirement: + dockerPull: docker-example-r-base ++ +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. + +
$ arv-keepdocker docker-example-r-base --project-uuid zzzzz-j7d0g-xxxxxxxxxxxxxxx
+
+