markdown source builds

Auto-generated via {sandpaper}
Source  : e87436e
Branch  : main
Author  : Jeremy Cohen <[email protected]>
Time    : 2024-08-16 09:01:46 +0000
Message : Merge pull request carpentries-incubator#246 from aturner-epcc/aturner-epcc/remove-jekyll

Removes defunct Jekyll example. Closes carpentries-incubator#245. Closes carpentries-incubator#216

advanced-containers.md

@@ -13,7 +13,11 @@ exercises: 30
 
 :::::::::::::::::::::::::::::::::::::::: questions
 
-- How can I make more complex container images?
+- How can I add local files (e.g. data files) into container
+  images at build time?
+
+- How can I access files stored on the host system from within a running Docker
+  container?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -46,8 +50,39 @@ container image.
 
 ## Running containers
 
-What command would we use to run Python from the `alpine-python` container?
+Question: What command would we use to run Python from the `alpine-python` container?
+
+
+:::::::::::::::  solution
+
+## Solution
+
+We can run a container from the alpine-python container image using:
+
+```bash
+$ docker container run alice/alpine-python
+```
+
+What happens? Since the `Dockerfile` that we built this container image from
+had a `CMD` entry that specified `["python3", "--version"]`, running the above
+command simply starts a container from the image, runs the `python3 --version`
+command and exits. You should have seen the installed version of Python printed
+to the terminal.
+
+Instead, if we want to run an interactive Python terminal, we can use `docker
+container run` to override the default run command embedded within the
+container image. So we could run:
 
+```bash
+$ docker container run -it alice/alpine-python python3
+```
+
+The `-it` tells Docker to set up and interactive terminal connection to the
+running container, and then we're telling Docker to run the `python3` command
+inside the container which gives us an interactive Python interpreter prompt.
+_(type `exit()` to exit!)_
+
+:::::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -65,9 +100,12 @@ python3: can't open file '//sum.py': [Errno 2] No such file or directory
 
 ## No such file or directory
 
-What does the error message mean? Why might the Python inside the container
+Question: What does the error message mean? Why might the Python inside the container
 not be able to find or open our script?
 
+This question is here for you to think about - we explore the answer to this
+question in the content below.
+
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 The problem here is that the container and its filesystem is separate from our

config.yaml

@@ -27,7 +27,7 @@ life_cycle: 'beta'
 license: 'CC-BY 4.0'
 
 # Link to the source repository for this lesson
-source: 'https://github.com/fishtree-attempt/docker-introduction/'
+source: 'https://github.com/carpentries-incubator/docker-introduction/'
 
 # Default branch of your lesson
 branch: 'main'

creating-container-images.md

@@ -272,7 +272,10 @@ There are a lot of choices when it comes to installing software -- sometimes too
 Here are some things to consider when creating your own container image:
 
 - **Start smart**, or, don't install everything from scratch! If you're using Python
-  as your main tool, start with a [Python container image](https://hub.docker.com/_/python). Same with [R](https://hub.docker.com/r/rocker/r-ver/). We've used Alpine Linux as an example
+  as your main tool, start with a [Python container
+  image](https://hub.docker.com/_/python). Same with the
+  [R programming language](https://hub.docker.com/r/rocker/r-ver/). We've used Alpine Linux as an
+  example
   in this lesson, but it's generally not a good container image to start with for initial development and experimentation because it is
   a less common distribution of Linux; using [Ubuntu](https://hub.docker.com/_/ubuntu), [Debian](https://hub.docker.com/_/debian) and [CentOS](https://hub.docker.com/_/centos) are all
   good options for scientific software installations. The program you're using might

docker-image-examples.md

@@ -1,7 +1,7 @@
 ---
 title: Examples of Using Container Images in Practice
-teaching: 20
-exercises: 0
+teaching: 10
+exercises: 15
 ---
 
 ::::::::::::::::::::::::::::::::::::::: objectives
@@ -21,13 +21,6 @@ let's apply what we learned to an example workflow.
 
 You may choose one or more of the following examples to practice using containers.
 
-## Jekyll Website Example
-
-In this [Jekyll Website example](../instructors/e02-jekyll-lesson-example.md), you can practice
-rendering this lesson website on your computer using the Jekyll static website generator in a Docker container.
-Rendering the website in a container avoids a complicated software installation; instead of installing Jekyll and all the other tools needed to create the final website, all the work can be done in the container.
-Additionally, when you no longer need to render the website, you can easily and cleanly remove the software from your computer.
-
 ## GitHub Actions Example
 
 In this [GitHub Actions example](../instructors/e01-github-actions.md), you can learn more about

index.md

@@ -48,6 +48,24 @@ If you are looking for a lesson on using Singularity containers (instead of Dock
 - The lessons will sometimes request that you use a text editor to create or edit files in particular directories. It is assumed that you either have an editor that you know how to use that runs within the working directory of your shell window (e.g. `nano`), or that if you use a graphical editor, that you can use it to read and write files into the working directory of your shell.
 
 
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## Target audience
+
+This lesson on the use of Docker is intended to be relevant to a wide range of
+researchers, as well as existing and prospective technical professionals. It is
+intended as a beginner level course that is suitable for people who have no
+experience of containers.
+
+We are aiming to help people who want to develop their knowledge of container
+tooling to help improve reproducibility and support their research work, or
+that of individuals or teams they are working with.
+
+We provide more detail on specific roles that might benefit from this course on
+the [Learner Profiles](/profiles.html) page.
+
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::::  callout

introduction.md

@@ -1,7 +1,7 @@
 ---
 title: Introducing Containers
 teaching: 20
-exercises: 0
+exercises: 5
 ---
 
 ::::::::::::::::::::::::::::::::::::::: objectives
@@ -64,7 +64,7 @@ to use likely depends on many, many, different other programs (including the
 operating system!), creating a very complex, and often fragile system. One change
 or missing piece may stop the whole thing from working or break something that was
 already running. It's no surprise that this situation is sometimes
-informally termed "dependency hell".
+informally termed **dependency hell**.
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
@@ -92,7 +92,7 @@ and access to resources such as files and communications networks in a uniform m
 
 ## What is a Container? What is Docker?
 
-[Docker][Docker] is a tool that allows you to build what are called "containers." It's
+[Docker][Docker] is a tool that allows you to build what are called **containers**. It's
 not the only tool that can create containers, but is the one we've chosen for
 this workshop. But what *is* a container?
 
@@ -103,7 +103,7 @@ called the hardware. One of these pieces is the CPU or processor; another is
 the amount of memory or RAM that your computer can use to store information
 temporarily while running programs; another is the hard drive, which can store
 information over the long-term. All these pieces work together to do the
-"computing" of a computer, but we don't see them because they're hidden from view (usually).
+computing of a computer, but we don't see them because they're hidden from view (usually).
 
 Instead, what we see is our desktop, program windows, different folders, and
 files. These all live in what's called the filesystem. Everything on your computer -- programs,
@@ -115,23 +115,23 @@ of making a mess of your existing system by installing a bunch of additional stu
 You don't want to buy a whole new computer because it's too expensive.
 What if, instead, you could have another independent filesystem and running operating system that you could access from your main computer, and that is actually stored within this existing computer?
 
-Or, imagine you have two tools you want to use in your groundbreaking research on cat memes: `PurrLOLing`, a tool that does AMAZINGLY well at predicting the best text for a meme based on the cat species and `WhiskerSpot`, the only tool available for identifying cat species from images.  You want to send cat pictures to `WhiskerSpot`, and then send the species output to `PurrLOLing`.  But there's a problem: `PurrLOLing` only works on Ubuntu and `WhiskerSpot` is only supported for OpenSUSE so you can't have them on the same system!  Again, we really want another filesystem (or two) on our computer that we could use to chain together `WhiskerSpot` and `PurrLOLing` in a "pipeline"...
+Or, imagine you have two tools you want to use in your groundbreaking research on cat memes: `PurrLOLing`, a tool that does AMAZINGLY well at predicting the best text for a meme based on the cat species and `WhiskerSpot`, the only tool available for identifying cat species from images.  You want to send cat pictures to `WhiskerSpot`, and then send the species output to `PurrLOLing`.  But there's a problem: `PurrLOLing` only works on Ubuntu and `WhiskerSpot` is only supported for OpenSUSE so you can't have them on the same system!  Again, we really want another filesystem (or two) on our computer that we could use to chain together `WhiskerSpot` and `PurrLOLing` in a **computational pipeline**...
 
 Container systems, like Docker, are special programs on your computer that make it possible!
-The term "container" can be usefully considered with reference to shipping
+The term container can be usefully considered with reference to shipping
 containers. Before shipping containers were developed, packing and unpacking
 cargo ships was time consuming and error prone, with high potential for
 different clients' goods to become mixed up. Just like shipping containers keep things
 together that should stay together, software containers standardize the description and
 creation of a complete software system: you can drop a container into any computer with
-the container software installed (the 'container host'), and it should "just work".
+the container software installed (the 'container host'), and it should *just work*.
 
 :::::::::::::::::::::::::::::::::::::::::  callout
 
 ## Virtualization
 
 Containers are an example of what's called **virtualization** -- having a
-second "virtual" computer running and accessible from a main or **host**
+second virtual computer running and accessible from a main or **host**
 computer. Another example of virtualization are **virtual machines** or
 VMs. A virtual machine typically contains a whole copy of an operating system in
 addition to its own filesystem and has to get booted up in the same way
@@ -153,6 +153,8 @@ can be used to create multiple copies of the same shape (or container)
 and is relatively unchanging, where cookies come and go. If you want a
 different type of container (cookie) you need a different container image (cookie cutter).
 
+![](fig/containers-cookie-cutter.png){alt='An image comparing using a cookie cutter to the container workflow'}
+
 ## Putting the Pieces Together
 
 Think back to some of the challenges we described at the beginning. The many layers