3rd pass

episodes/docker-cli-toolkit.Rmd

@@ -258,6 +258,8 @@ Welcome to the Space Purple Unicorn Counter!
 
 :: Try recording a unicorn sighting with:
     curl -X PUT localhost:8321/unicorn_spotted?location=moon\&brightness=100
+
+:: No plugins detected
 ```
 
 And there we have it! The SPUC container is running and ready to count unicorns.
@@ -429,15 +431,32 @@ connectivity on endpoint spuc_container (67e075648d16fafdf086573169d891bee9b33be
 Oops! It looks like we already have a container running on port 8321.
 Of course, it is the container that we ran earlier, unruffled_noyce, and we can't have two containers running on the same port!
 
-To fix this, we can stop the container that is running on port 8321 using the `docker stop` command:
+To fix this, we can stop and remove the container that is running on port 8321 using the `docker stop` command:
 ```bash
 docker stop unruffled_noyce
+docker rm unruffled_noyce
 ```
 ```output
 unruffled_noyce
+unruffled_noyce
 ```
 
-**Note:** Using `docker kill <container_name>`, will also work, although it is best to leave that as a last resort.
+::::::::::::::::::::::::::::::::::::::: callout
+
+### Killing containers
+Using `docker kill <container_name>`, will immediately stop a container.
+This is usually recommended against as a standard, and should be left as a last resort.
+However, in practice it is very often used.
+
+The SPUC container, in particular, responds very slowly to the `stop` signal, so we will use `kill` going forward.
+Try it with the other container we left running in the background:
+```bash
+docker kill ecstatic_nightingale
+```
+```output
+ecstatic_nightingale
+```
+:::::::::::::::::::::::::::::::::::::::::::::::
 
 Right, now we can try running the container again:
 ```bash
@@ -587,7 +606,7 @@ We can of course do the same thing in the Docker CLI.
 
 To show this, lets first stop the container we have running:
 ```bash
-docker stop spuc_container
+docker kill spuc_container
 ```
 ```output
 spuc_container
@@ -619,10 +638,10 @@ As we can see, the container is alive and well, and we can now exec into it agai
 ## Cleaning up
 
 The last thing we need to know is how to clean up after ourselves.
-We can do this using the `docker rm` command to remove a container,
-and the `docker image rm` command to remove an image:
+We have already removed a container using the `docker rm` command,
+and we can use the `docker image rm` command to remove an image:
 ```bash
-docker stop spuc_container
+docker kill spuc_container
 ```
 ```output
 spuc_container
@@ -720,6 +739,7 @@ We will cover these in the next episode.
 | `docker logs <container>`       | Show the logs of a container                    |
 | `docker exec <container> <cmd>` | Run a command in a running container            |
 | `docker stop <container>`       | Stop a running container                        |
+| `docker kill <container>`       | Immediately stop a running container            |
 | `docker start <container>`      | Start a stopped container                       |
 | `docker rm <container>`         | Remove a container                              |
 | **System**                      |                                                 |

episodes/docker-desktop.Rmd

@@ -115,7 +115,7 @@ You might also find the heading in this page strange.
 Unless you specify a name for the container (which we could have done in the optional settings),
 Docker will generate a random name for it, which is what we see here.
 
-Exploring the `Inspect` tab will show us some information, but for now we are more interested in what the `Terminal` and `Stats` tabs have to say.
+Exploring the `Inspect` tab will show us some information, but for now we are more interested in what the `Exec` and `Stats` tabs have to say.
 They both seem to indicate that we need to *run* or *start* the container.
 
 ::: tab
@@ -223,7 +223,7 @@ The `Exec` tab also looks more interesting, we get access to a terminal inside t
 
 :::
 
-Before trying to do anything in the terminal, let`s look at the container list by clicking on the `Containers` tab on the left.
+Before trying to do anything in the terminal, let's look at the container list by clicking on the `Containers` tab on the left.
 You'll see the green icon of the container indicating that it is still live, and indication of how long it's been running for.
 
 ![](fig/docker-desktop/containers_list_spuc_running.png){alt='Containers list, spuc still running.'}
@@ -236,7 +236,10 @@ Clicking on the container name again will take us back to the `Logs` tab in the
 
 If you look at the logs, you'll see that the SPUC container is instructing you on how to interact with it.
 Lets go ahead and try that.
-Open a terminal and run the command `curl -X PUT localhost:8321/unicorn_spotted?location=moon\&brightness=100`.
+Open a terminal and run the command
+```bash
+curl -X PUT localhost:8321/unicorn_spotted?location=moon\&brightness=100
+```
 If you look at the logs again, you'll see that the container has responded to your command with something like:
 
 ![](fig/docker-desktop/spuc_unicorn_detected.png){alt='Detecting a unicorn, spuc logs.'}
@@ -370,8 +373,7 @@ However, we've not touched on its weaknesses.
 
 One thing we have completely lost now is the record of our unicorn sightings.
 The containers are gone, and so are the changes we made to the `print.config` file.
-Data in the containers can be made persistent, but it is not the default behaviour,
-and it is not something you can do from Docker Desktop!
+Data in the containers can be made persistent, but it is not the default behaviour.
 
 Another very important thing is that Docker Desktop is very limited in *how* you can run the containers.
 The optional settings let you modify the instruction with which the container is run, but it is very limited.

episodes/docker-run-configuration.Rmd

@@ -41,11 +41,11 @@ Welcome to the Space Purple Unicorn Counter!
 
 :::: Units set to Imperial Unicorn Hoove Candles [iuhc] ::::
 
-:: No plugins detected
-
 :: Try recording a unicorn sighting with:
     curl -X PUT localhost:8321/unicorn_spotted?location=moon\&brightness=100
 
+:: No plugins detected
+
 :::: Unicorn sightings export activated! ::::
 :: Try downloading the unicorn sightings record with:
     curl localhost:8321/export
@@ -96,14 +96,13 @@ This is actually a very common thing to do when running containers.
 It is done by passing a parameter at the end of our `run` command, after the image name:
 ```bash
 docker stop spuc_container
-docker rm spuc-volume
 docker run -d --rm --name spuc_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -e EXPORT=true spuacv/spuc:latest --units iulu
 ```
 
 if we now register some unicorn sightings, we should see the brightness in iulu units.
 ```bash
 curl -X PUT localhost:8321/unicorn_spotted?location=pluto\&brightness=66
-curl localhost:8321/export/
+curl localhost:8321/export
 ```
 ```output
 count,time,location,brightness,units
@@ -119,25 +118,24 @@ We can already feel the weight lifting off our shoulders already!
 But we cannot mix iuhcs with iulus, so lets remove the volume and re-register our sightings with the correct units
 ```bash
 docker stop spuc_container
-docker rm spuc-volume
+docker volume rm spuc-volume
 docker run -d --rm --name spuc_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -e EXPORT=true spuacv/spuc:latest --units iulu
 curl -X PUT localhost:8321/unicorn_spotted?location=moon\&brightness=177
 curl -X PUT localhost:8321/unicorn_spotted?location=earth\&brightness=18
 curl -X PUT localhost:8321/unicorn_spotted?location=mars\&brightness=709
 curl -X PUT localhost:8321/unicorn_spotted?location=jupyter\&brightness=372
 curl -X PUT localhost:8321/unicorn_spotted?location=venus\&brightness=262
 curl -X PUT localhost:8321/unicorn_spotted?location=pluto\&brightness=66
-curl localhost:8321/export/
+curl localhost:8321/export
 ```
 ```output
 count,time,location,brightness,units
-1,2024-10-16 09:14:17.719447,moon,100,iuhc
-2,2024-10-16 09:14:17.726706,earth,10,iuhc
-3,2024-10-16 09:14:17.732191,mars,400,iuhc
-4,2024-10-16 10:53:13.449393,jupyter,100,iuhc
-5,2024-10-16 12:49:52.512391,jupyter,100,iuhc
-6,2024-10-16 12:50:10.581131,jupyter,100,iuhc
-7,2024-10-16 12:53:51.726902,venus,148,iuhc
+1,2024-10-16 13:15:03.719371,moon,177,iulu
+2,2024-10-16 13:15:03.719398,earth,18,iulu
+3,2024-10-16 13:15:03.719410,mars,709,iulu
+6,2024-10-16 13:15:03.719425,jupyter,372,iulu
+5,2024-10-16 13:15:03.719437,venus,262,iulu
+6,2024-10-16 13:15:03.719447,pluto,66,iulu
 ```
 
 Finally, we have the correct units for the brightness of the unicorns!

episodes/docker-volumes.Rmd

@@ -46,9 +46,11 @@ or for persisting data between runs of a container.
 Let's have a look at how we can use a volume to persist the `unicorn_sightings.txt` file between runs of the container.
 We do this by modifying our `run` command to include a `-v` (for volume) flag, a volume name and a path inside the container.
 ```bash
+docker kill spuc_container
 docker run -d --rm --name spuc_container -p 8321:8321 -v spuc-volume:/spuc/output spuacv/spuc:latest
 ```
 ```output
+spuc_container
 f1bd2bb9062348b6a1815f5076fcd1b79e603020c2d58436408c6c60da7e73d2
 ```
 
@@ -116,7 +118,7 @@ count,time,location,brightness,units
 Now, for our test, we will stop the container.
 Since we used the `-rm` flag, the container will also be deleted.
 ```bash
-docker stop spuc_container
+docker kill spuc_container
 docker ps -a
 ```
 ```output
@@ -154,7 +156,7 @@ However, instead of a name for the volume, we have to specify a path on the host
 
 **Note:** In older versions of Docker the path had to be *absolute*; *relative* paths are now supported.
 ```bash
-docker stop spuc_container
+docker kill spuc_container
 docker run -d --rm --name spuc_container -p 8321:8321 -v ./spuc/output:/spuc/output spuacv/spuc:latest
 ```
 ```output
@@ -178,7 +180,7 @@ count,time,location,brightness,units
 
 and the file is still there even after stopping the container
 ```bash
-docker stop spuc_container
+docker kill spuc_container
 ls spuc/output
 ```
 ```output
@@ -209,6 +211,8 @@ ls -l spuc/unicorn_sightings.txt
 -rw-r--r-- 1 root root 57 Oct 11 14:14 spuc/unicorn_sightings.txt
 ```
 
+**Note:** This no longer seems to be the case from Docker version 27.3.1 onwards.
+
 Argh, the file is owned by root!
 This is because the container runs as root, and so any files created by the container are owned by root.
 This can be a problem, as you will not have permission to access the file without using `sudo`.
@@ -239,7 +243,7 @@ echo "::::: {time} Unicorn number {count} spotted at {location}! Brightness: {br
 Now, to share it with the container, we need to put it in the path `/spuc/config/print.config`.
 Again we will use `-v`, but we will specify the path to the file, instead of a directory.
 ```bash
-docker stop spuc_container
+docker kill spuc_container
 docker run -d --rm --name spuc_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output spuacv/spuc:latest
 ```
 

episodes/dockerfiles.Rmd

@@ -53,9 +53,11 @@ We already know how to load this file.
 Let's use a bind mount to share the file with the container.
 Since we are debugging, we'll leave out the `-d` flag so we can see the output easily.
 ```bash
-docker run --rm --name spuc_container -p 8321:8321 -v $PWD/print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -v $PWD/stats.py:/spuc/plugins/stats.py -e EXPORT=true spuacv/spuc:latest --units iulu
+docker kill spuc_container
+docker run --rm --name spuc_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -v ./stats.py:/spuc/plugins/stats.py -e EXPORT=true spuacv/spuc:latest --units iulu
 ```
 ```output
+[...]
 Traceback (most recent call last):
   File "/spuc/spuc.py", line 31, in <module>
     __import__(f"{plugin_dir}.{plugin[:-3]}")
@@ -112,7 +114,7 @@ docker build -t spuc-stats ./
  => [internal] load metadata for docker.io/spuacv/spuc:latest                                          0.0s
  => [internal] load .dockerignore                                                                      0.0s
  => => transferring context: 2B                                                                        0.0s
- => CACHED [1/1] FROM docker.io/spuacv/spuc:latest                                                     0.0s
+ => [1/1] FROM docker.io/spuacv/spuc:latest                                                            0.1s
  => exporting to image                                                                                 0.0s
  => => exporting layers                                                                                0.0s
  => => writing image sha256:ccde35b1f9e872bde522e9fe91466ef983f9b579cffc2f457bff97f74206e839           0.0s
@@ -202,7 +204,7 @@ Welcome to the Space Purple Unicorn Counter!
 So we have a copy of the SPUC image with a new name, but nothing has changed!
 In fact, we can pass all the same arguments to the `docker run` command as we did before:
 ```bash
-docker run --rm --name spuc-stats_container -p 8321:8321 -v $PWD/print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -v $PWD/stats.py:/spuc/plugins/stats.py -e EXPORT=true spuc-stats --units iulu
+docker run --rm --name spuc-stats_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -v ./stats.py:/spuc/plugins/stats.py -e EXPORT=true spuc-stats --units iulu
 ```
 ```output
 Traceback (most recent call last):
@@ -245,7 +247,7 @@ so we can ignore this warning.
 
 Let's run the image again:
 ```bash
-docker run --rm --name spuc-stats_container -p 8321:8321 -v $PWD/print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -v $PWD/stats.py:/spuc/plugins/stats.py -e EXPORT=true spuc-stats --units iulu
+docker run --rm --name spuc-stats_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -v ./stats.py:/spuc/plugins/stats.py -e EXPORT=true spuc-stats --units iulu
 ```
 ```output
 [...]
@@ -325,7 +327,7 @@ and only had to do some work for the `COPY` layer.
 
 And run the image again, but this time without the bind mount for the `stats.py` file:
 ```bash
-docker run --rm --name spuc-stats_container -p 8321:8321 -v $PWD/print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -e EXPORT=true spuc-stats --units iulu
+docker run --rm --name spuc-stats_container -p 8321:8321 -v ./print.config:/spuc/config/print.config -v spuc-volume:/spuc/output -e EXPORT=true spuc-stats --units iulu
 ```
 ```output
 [...]

learners/setup.md

@@ -122,7 +122,7 @@ You can also find a summary of the steps below (buyer beware!).
 To check if the Docker and client and server are working run the following command in a new terminal session:
 
 ```bash
-$ docker version
+docker version
 ```
 ```output
 Client: Docker Engine - Community