Merge pull request #123 from UoMResearchIT/oct2025_review_FHA

Oct2025 review fha

Author: OliverWoolland

code/docker-compose.yml code/compose.ymlcode/docker-compose.yml renamed to code/compose.yml

@@ -56,7 +56,7 @@ volumes:
 Image: Apperture Services: Showing a user accessing WhoAmI via the web portal, which is protected by Authelia, which authenticates against an LDAP server, which pulls user data from a Postgres database.
 ## Combining Stacks
 ```yml
-# SPUC docker-compose.yml
+# SPUC compose.yml
 
 + networks:
 +   apperture:

code/episodes/docker-compose-microservices.md

@@ -1,7 +1,7 @@
 ---
 title: Building our Docker CLI toolkit
-teaching: 99
-exercises: 99
+teaching: 40
+exercises: 0
 ---
 
 Before we start to tackle Docker tasks that are only possible in the command line,

episodes/docker-cli-toolkit.Rmd

@@ -1,7 +1,7 @@
 ---
 title: And they lived happily ever after
-teaching: 99
-exercises: 99
+teaching: 10
+exercises: 0
 ---
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::: objectives
@@ -52,7 +52,7 @@ It is maintained by the University of Manchester's Research IT team, and can eas
 `Apperture` is comprised primarily of a compose file.
 Just like we have been looking at!
 
-The full `docker-compose.yml` file is available [on github](https://raw.githubusercontent.com/UoMResearchIT/apperture/refs/heads/main/docker-compose.yml).
+The full `compose.yml` file is available [on github](https://raw.githubusercontent.com/UoMResearchIT/apperture/refs/heads/main/docker-compose.yml).
 It is quite long, so we will reproduce a slimmed down version here.
 
 ```yml
@@ -105,15 +105,15 @@ volumes:
   lldap-postgres-data:
 ```
 
-This `docker-compose.yml` file is a little more complex than the ones we have been looking at so far, but it is still just a list of services and their configurations.
+This `compose.yml` file is a little more complex than the ones we have been looking at so far, but it is still just a list of services and their configurations.
 
 You'll see some familiar things, like `image`, `ports`, `depends_on` (and `healthchecks`), `volumes`, and `environment`.
 
-Notice the `image` field in the `services` section of the `docker-compose.yml` file.
+Notice the `image` field in the `services` section of the `compose.yml` file.
 Every service is using a pre-built Docker image from Docker Hub, straight off the shelf!
 This is the power of Docker Compose and microservices!
 
-To get an idea of what is going on, let's draw a diagram of the services in the `docker-compose.yml` file.
+To get an idea of what is going on, let's draw a diagram of the services in the `compose.yml` file.
 
 ![](fig/docker_compose_apperture.png){alt='Apperture Services: Showing a user accessing WhoAmI via the web portal, which is protected by Authelia, which authenticates against an LDAP server, which pulls user data from a Postgres database.'}
 
@@ -128,13 +128,13 @@ There is no reason we cannot combine the Apperture stack with the SPUC stack we
 This would allow us to protect our SPUC interface with the Apperture portal.
 An important addition! We need to ensure poachers cannot falsely record sightings of the rare yet valuable unicorns!
 
-This can be achieved by making a couple of changes to the SPUC `docker-compose.yml` file.
+This can be achieved by making a couple of changes to the SPUC `compose.yml` file.
 
 In our previous lesson, we learned about networks, which allow services to communicate with each other.
 Now we want join the networks of the SPUC and Apperture stacks so that they can communicate with each other.
 
 ```yml
-# SPUC docker-compose.yml
+# SPUC compose.yml
 
 + networks:
 +   apperture:

episodes/docker-compose-microservices.Rmd

@@ -1,7 +1,7 @@
 ---
 title: Using Docker Compose
-teaching: 99
-exercises: 99
+teaching: 60
+exercises: 0
 ---
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::: objectives
@@ -11,7 +11,7 @@ exercises: 99
 ::::::::::::::::::::::::::::::::::::::::::::::::::: questions
 - What is Docker Compose?
 - Why and when would I use it?
-- How can I translate my `docker run` commands into a `docker-compose.yml` file?
+- How can I translate my `docker run` commands into a `compose.yml` file?
 - How can I make containers communicate with each other?
 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -39,8 +39,8 @@ Let's take a look at Docker Compose and see how it can help us run SPUC and SPUC
 
 As an initial step, we will learn how to run a container using Docker Compose.
 
-The first thing we need to do is create a `docker-compose.yml` file.
-All `docker-compose.yml` files start with `services:`.
+The first thing we need to do is create a `compose.yml` file.
+All `compose.yml` files start with `services:`.
 This is the root element under which we define the services we want to run.
 ```yml
 services:
@@ -124,7 +124,7 @@ docker run -d --rm --name spuc_container -p 8321:8321 -v ./print.config:/spuc/co
 
 There are a lot of flags here!
 Each of these flags has a corresponding key in Docker Compose.
-Lets order all the elements we want in a table, so we can see what we need to add to our `docker-compose.yml` file.
+Lets order all the elements we want in a table, so we can see what we need to add to our `compose.yml` file.
 
 | Flag                                          | Description                                             |
 |-----------------------------------------------|---------------------------------------------------------|
@@ -273,7 +273,7 @@ docker compose up -d
 
 You do not necessarily need to `down` your containers to update the configuration, Docker Compose can be *smart* like that.
 
-You can update the `docker-compose.yml` file in your text editor and then run `docker compose up -d` to see the changes take effect.
+You can update the `compose.yml` file in your text editor and then run `docker compose up -d` to see the changes take effect.
 
 **Warning**: This is not always foolproof! Some changes will require a rebuild of the container.
 It is also worth noting that Docker Compose does not *save* the status with which you started your services.
@@ -552,7 +552,26 @@ Let's go back to that.
 
 ## Building containers in Docker Compose
 
-We could use the tag we used when we built the container to use that image.
+We could use the tag we used when we built the container to use that image:
+```yml
+services:
+  spuc:
+    image: spuc-stats   # Use the image we built earlier
+    container_name: spuc_container
+    ports:
+      - 8321:8321
+    volumes:
+      - ./print.config:/spuc/config/print.config
+      - spuc-volume:/spuc/output
+      - ./stats.py:/spuc/plugins/stats.py        # Mounts the stats.py plugin
+    environment:
+      - EXPORT=true
+    command: ["--units", "iulu"]
+
+volumes:
+  spuc-volume:
+```
+
 However, this would mean that if we want to adjust our locally built container, we would have to rebuild it separately.
 
 Instead, we can use the `build` key to tell Docker Compose to build the container if needed.
@@ -561,7 +580,7 @@ To do that, we use the `build` key instead of the `image` key:
 ```yml
 services:
   spuc:
-  # image: spuacv/spuc:latest
+  # image: spuc-stats
     build:                        # Instead of using the 'image' key, we use the 'build' key
       context: .                  # Sets the build context (the directory in which the Dockerfile is located)
       dockerfile: Dockerfile      # Sets the name of the Dockerfile
@@ -575,6 +594,9 @@ services:
     environment:
       - EXPORT=true
     command: ["--units", "iulu"]
+
+volumes:
+  spuc-volume:
 ```
 
 This tells docker compose to look for the Dockerfile in the current directory.
@@ -585,7 +607,7 @@ If we run `up`, Docker Compose will default to checking if the image exists and
 This is ok... unless we have made changes to the Dockerfile!
 
 To ensure that the image is built, we can run `docker compose build`.
-This will build (all) the image(s) specified inside our `docker-compose.yml`.
+This will build (all) the image(s) specified inside our `compose.yml`.
 After building, we use the usual `up` command.
 
 Alternatively, we can add the `--build` flag to the `up` command, which results in Docker building the image right before starting the container.
@@ -632,7 +654,7 @@ You should now have a container running with the stats plugin enabled!
 
 #### Simpler Dockerfile
 
-You may have noticed that we ended up *duplicating* most of the configuration from the Dockerfile within the `docker-compose.yml` file.
+You may have noticed that we ended up *duplicating* most of the configuration from the Dockerfile within the `compose.yml` file.
 
 In reality, if we are using Docker Compose we do not need to bake in all of the configuration inside the Dockerfile.
 The only thing that was different was the `pip install pandas` command.
@@ -642,9 +664,9 @@ FROM spuacv/spuc:latest
 RUN pip install pandas
 ```
 
-Alternatively, we could simplify our `docker-compose.yml` file by removing the duplicated configuration.
-However, this would make the `docker-compose.yml` file less self-contained and more dependent on the Dockerfile.
-It is usually a better idea to keep the configuration in the `docker-compose.yml` file, as it makes it easier to understand and maintain.
+Alternatively, we could simplify our `compose.yml` file by removing the duplicated configuration.
+However, this would make the `compose.yml` file less self-contained and more dependent on the Dockerfile.
+It is usually a better idea to keep the configuration in the `compose.yml` file, as it makes it easier to understand and maintain.
 
 :::::::::::::::::::::::::::::::::::
 
@@ -843,9 +865,9 @@ For example in a typical web app you may make it so that the frontend can connec
 #### Network names
 
 You may have noticed that the network that Docker Compose created for our stack is named `docker_intro_default`.
-This is because Docker Compose uses the name of the directory that the `docker-compose.yml` file is in as the name of the network.
+This is because Docker Compose uses the name of the directory that the `compose.yml` file is in as the name of the network.
 
-If you want to specify the name of the network, you can use the `networks` key in the `docker-compose.yml` file.
+If you want to specify the name of the network, you can use the `networks` key in the `compose.yml` file.
 You also need to specify the network name for each service that you want to connect to the network.
 
 For example, to specify the network name as `spuc_network`, you would add the following to the file:
@@ -1099,7 +1121,7 @@ The SPUC service shows an error, because it failed all 5 retries, and the SPUCSV
 ::::::::::::::::::::::::::::::::::::::::::::::::::: keypoints
 - Docker Compose is a tool for defining and running multi-container stacks in a YAML file.
   They can also serve as a way of structuring and documenting `docker run` commands for single containers.
-- Instructions are saved in a `docker-compose.yml` file, where services, networks, and volumes are defined.
+- Instructions are saved in a `compose.yml` file, where services, networks, and volumes are defined.
 - Each `service` is a separate container, and it can be fully configured from within the file.
 - Bind mounts and `volumes` can be declared for each service, and they can be shared between containers too.
 - You can define `networks`, which can be used to connect or isolate containers from each other.

episodes/docker-compose.Rmd

@@ -1,6 +1,6 @@
 ---
 title: Docker Desktop
-teaching: 20
+teaching: 40
 exercises: 0
 ---
 
@@ -494,6 +494,10 @@ There is a very convenient bin icon on the right, which will prompt you for conf
 :::
 
 You should now be able to run the `spuc` image again, and name the container `SPUC`.
+However, if you try to add the port you'll find that you still have a conflict.
+This is because the port is still in use by the old container, even though it is stopped.
+If you delete the randomly named container which had the port map,
+you should be able to run the image with the name and port you want.
 
 Since we are deleting stuff, the `hello-world` image was nice and useful to test docker was working, but it is now rather useless.
 If I want to delete it, the `Images` tab on the left has a convenient bin icon to do so.
@@ -513,7 +517,7 @@ Clicking on it will prompt you for confirmation, but it will fail.
 :::
 
 You'll probably notice that the status of the image is `In use`.
-That seems strange though, given that all the containers from that image excited immediately.
+That seems strange though, given that all the containers from that image exited immediately.
 
 Lets have a look at the `Containers` tab.
 Some of the containers in the list came from the `hello-world` image.

episodes/docker-desktop.Rmd

@@ -1,7 +1,7 @@
 ---
 title: The Docker Hub
-teaching: 99
-exercises: 99
+teaching: 5
+exercises: 0
 ---
 
 So we want to look at the docs for a container image, but we don't want Docker Desktop anymore!

episodes/docker-hub.Rmd

@@ -1,7 +1,7 @@
 ---
 title: Configuring containers
-teaching: 99
-exercises: 99
+teaching: 30
+exercises: 0
 ---
 
 Well this is interesting!

episodes/docker-run-configuration.Rmd

@@ -1,7 +1,7 @@
 ---
 title: Sharing information with containers
-teaching: 99
-exercises: 99
+teaching: 45
+exercises: 0
 ---
 
 Now that we have learned the basics of the Docker CLI,
@@ -205,10 +205,10 @@ This is great!... but there are downsides.
 
 To illustrate this, let's see what the permissions are on the file we just created.
 ```bash
-ls -l spuc/unicorn_sightings.txt
+ls -l spuc/output/unicorn_sightings.txt
 ```
 ```output
--rw-r--r-- 1 root root 57 Oct 11 14:14 spuc/unicorn_sightings.txt
+-rw-r--r-- 1 root root 57 Oct 11 14:14 spuc/output/unicorn_sightings.txt
 ```
 
 **Note:** This no longer seems to be the case from Docker version 27.3.1 onwards.
@@ -234,10 +234,33 @@ This was a bit difficult, as we had to do it from inside the container, and it d
 We now have the tools to address this!
 We can use a bind mount to share the config file with the container.
 
-First we need to make the config file itself.
-Let's create a file with the following content:
+::::::::::::::::::::::::::::::::::::::: callout
+
+## Docker cp
+
+We can get files in and out of containers using the `docker cp` command.
+
+Let's try this to get the `print.config` file out of the container.
+It works like the `cp` command, but you have to specify the container name and path:
 ```bash
-echo "::::: {time} Unicorn number {count} spotted at {location}! Brightness: {brightness} {units}" > print.config
+docker cp spuc_container:/spuc/config/print.config .
+cat print.config
+```
+```output
+# This file configures the print output to the terminal.
+# Available variables are: count, time, location, brightness, units
+# The values of these variables will be replaced if wrapped in curly braces.
+# Lines beginning with # are ignored.
+::::: Unicorn spotted at {location}!! Brightness: {brightness} {units}
+```
+
+Note that this **will not keep changes in sync** like a bind mount, but it is useful for getting files in and out of containers.
+
+:::::::::::::::::::::::::::::::::::::::
+
+Let's now modify the print.config file to include the time and the unicorn count:
+```
+::::: {time} Unicorn number {count} spotted at {location}! Brightness: {brightness} {units}
 ```
 
 Now, to share it with the container, we need to put it in the path `/spuc/config/print.config`.
@@ -263,8 +286,8 @@ Not only that, but because we created the file before mounting it to the contain
 Changes to the file will reflect immediately on the container.
 
 For example, let's edit the file to get rid of the date:
-```bash
-echo "::::: Unicorn number {count} spotted at {location}! Brightness: {brightness} {units}" > print.config
+```
+::::: Unicorn number {count} spotted at {location}! Brightness: {brightness} {units}
 ```
 Now let's register a sighting, and look at the logs:
 ```bash

episodes/docker-volumes.Rmd

@@ -1,7 +1,7 @@
 ---
 title: Creating Your Own Container Images
-teaching: 99
-exercises: 99
+teaching: 60
+exercises: 0
 ---
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::: objectives