markdown source builds

Auto-generated via `{sandpaper}`
Source  : 79a2f1a
Branch  : main
Author  : Andy Turner <[email protected]>
Time    : 2024-10-12 18:26:43 +0000
Message : Merge pull request carpentries-incubator#247 from aturner-epcc/aturner-epcc/objective-i229

Improves objective. Closes carpentries-incubator#229

advanced-containers.md

@@ -50,9 +50,40 @@ 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!)_
+
+:::::::::::::::::::::::::
+
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 If we try running the container and Python script, what happens?
@@ -69,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

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-hub.md

@@ -6,7 +6,7 @@ exercises: 10
 
 ::::::::::::::::::::::::::::::::::::::: objectives
 
-- Explain how the Docker Hub augments Docker use.
+- Understand the importance of container registries such as Docker Hub, quay.io, etc.
 - Explore the Docker Hub webpage for a popular Docker container image.
 - Find the list of tags for a particular Docker container image.
 - Identify the three components of a container image's identifier.

docker-image-examples.md

@@ -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

@@ -45,6 +45,17 @@ scientific software (or software in general!) for your research. Then,
 share with your neighbors and try to come up with a list of common gripes or
 challenges.
 
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::::  callout
+
+## What is a software *dependency*?
+
+We will mention software *dependencies* a lot in this section of the workshop
+so it is good to clarify this term up front. A software dependency is a
+relationship between software components where one component relies on the
+other to work properly. For example, if a software application uses a library
+to query a database, the application depends on that library.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -66,6 +77,8 @@ or missing piece may stop the whole thing from working or break something that w
 already running. It's no surprise that this situation is sometimes
 informally termed **dependency hell**.
 
+
+
 :::::::::::::::::::::::::::::::::::::::  challenge
 
 ## Software and Science
@@ -90,41 +103,21 @@ Thankfully there are ways to get underneath (a lot of) this mess: containers
 to the rescue! Containers provide a way to package up software dependencies
 and access to resources such as files and communications networks in a uniform manner.
 
-## What is a Container? What is Docker?
-
-[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?
-
-To understand containers, let's first talk briefly about your computer.
+## What is a Container?
 
-Your computer has some standard pieces that allow it to work -- often what's
-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).
-
-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,
-pictures, documents, the operating system itself -- lives somewhere in the filesystem.
-
-NOW, imagine you want to install some new software but don't want to take the chance
-of making a mess of your existing system by installing a bunch of additional stuff
-(libraries/dependencies/etc.).
+Imagine you want to install some research software but don't want to take the chance of making a mess of your existing system by installing a bunch of additional stuff (libraries/dependencies/etc.).
 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 **computational pipeline**...
+More concretely, Docker Inc use the following definition of a container:
+
+> A container is a standard unit of software that packages up code and all its dependencies so the application runs reliably from one computing environment to another.
+
+<https://www.docker.com/resources/what-container/>
 
-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
-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 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*.
 
 :::::::::::::::::::::::::::::::::::::::::  callout
 
@@ -143,6 +136,14 @@ flavour of Linux + the filesystem inside.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+
+## What is Docker?
+
+[Docker][Docker] is a tool that allows you to build and run containers.
+It's not the only tool that can create containers, but is the one we've chosen for this workshop.
+
+## Container Images
+
 One final term: while the **container** is an alternative filesystem layer that you
 can access and run from your computer, the **container image** is the 'recipe' or template
 for a container. The container image has all the required information to start