add comments on clarity, update TIP for pip install requirements.txt

- clarity regarding Docker, Dockerfile, stopping containers started without interactive mode
- add some instructions, specify port number explicitly

Author: Xronophobe

chapter_09_docker.asciidoc

@@ -241,6 +241,7 @@ How will containerizing our software help with the danger areas?
 
 // TODO: consider getting rid of the staging server??
 
+////
 
 old content follows. is there anything we want to rescue from here?
 
@@ -535,7 +536,9 @@ But it's a little less well established and documented,
 (the Windows installation instructions are a little more DIY for example),
 and in the end, although I'm a fan of a plucky upstart,
 Docker is open source too,
-so I didn't decide to stick with Docker. But you could definitely check it out!
+so I decided to stick with Docker. But you could definitely check it out!
+// CSANAD:  Based on the premises in the sentence and the fact that we are using Docker
+// all along the chapter, I think it was meant to be like this.
 
 You can follow along all the instructions in the book
 by just substituing the `docker` binary for `podman` in all the CLI instructions,
@@ -576,6 +579,11 @@ What do we need to do?  Something like this, right?
 
 .Dockerfile (ch09l003)
 ====
+
+// CSANAD:  I think just a few words would be nice here, such as: "let's create
+//          a new file called `Dockerfile` next to the `src/` directory we've just
+// created."
+
 [source,dockerfile]
 ----
 FROM python:slim  <1>
@@ -644,6 +652,9 @@ $ pass:quotes[*docker build -t superlists .*]
  => => naming to docker.io/library/superlists                         0.0s
 ----
 
+// CSANAD:  Just a note: this output is slightly smaller and faster compared to when
+//          the reader first runs the `docker build`.
+
 Now we can see our image in the list of docker images on the system:
 
 [subs="specialcharacters,quotes"]
@@ -812,6 +823,14 @@ TIP: Forgetting the `-r` and running `pip install requirements.txt`
     because (at the time of writing), it's not very self-explanatory.
     And it's a mistake I still make, _all the time_.
 
+// CSANAD: This is no longer true, the error message is very helpful by now:
+//
+//   $ pip install requirements.txt
+//   ERROR: Could not find a version that satisfies the requirement requirements.txt (from versions: none)
+//   HINT: You are attempting to install a package literally named "requirements.txt" (which cannot exist). Consider using the '-r' flag to install the packages listed in requirements.txt
+//   ERROR: No matching distribution found for requirements.txt
+
+
 
 ==== Successful run
 
@@ -862,7 +881,14 @@ WARNING: Make sure you use the `-it` flags to the Docker `run`
     to be run in an interactive terminal session,
     otherwise you'll get strange behaviours, including not being able
     to interrupt the docker process with _Ctrl-C_.
-
+    In case it already happened, you can terminate it using
+    `docker stop <container_id>`.
+    Also, it's worth mentioning that you can specify just enough characters
+    of the container ID that uniquely identifies the container - e.g. if you
+    have a container with the ID `abcdef123456` and no other container ID
+    starts with `a`, you can use just `a` to reference this container in your
+    Docker commands:
+    `docker stop a`.
 
 
 
@@ -887,12 +913,15 @@ Nope!  What's going on here?  Time for a little debugging.
 
 === Debugging a Container Networking Problems
 
-First let's try and take a look ourselves, in our browser:
+First let's try and take a look ourselves, in our browser. Let's visit http://localhost:8888/:
 
 [[firefox-unable-to-connect-screenshot]]
 .Cannot connect on that port
 image::images/firefox-unable-to-connect.png["Firefox showing the 'Unable to connect' error"]
 
+// CSANAD:  Some more specific instructions were missing. We didn't specify the address.
+//          Based on the following text I think it's supposed to be
+// http://localhost:8888 here but of course, it would fail with any other port as well.
 
 Now let's take another look at the output from our `docker run`.  Here's what appeared right at the end:
 
@@ -903,8 +932,10 @@ Starting development server at http://127.0.0.1:8000/
 Quit the server with CONTROL-C.
 ----
 
-Aha!  We notice that we're using the wrong port, `8000` instead of the `8888`
+Aha!  We notice that we're using the wrong port, the default `8000` instead of the `8888`
 that we specified in the `TEST_SERVER` env var.
+// CSANAD:  since we haven't specified :8000 explicitly either, maybe this sentence is
+// clearer with this extra word "default".
 
 Let's fix that by amending the `CMD` instruction in the Dockerfile: