work thru csanads comments

Author: hjwp

chapter_09_docker.asciidoc

@@ -150,40 +150,24 @@ But that can be fiddly to set up!
 And nowadays, thanks to containerization, we can do better.
 Because containerization is a kind of even-more-virtual virtualization.
 
-Conceptually, "regular" virtualization works at the hardware level,
+Conceptually, "regular" virtualization works at the hardware level:
 it gives you multiple virtual machines (VMs)
 that pretend to be physical computers, on a single real machine.
 So you can run multiple operating systems using separate VMs
 on the same physical box.
-// CSANAD:  to me, the wording sounded like it meant the multiple OS-s
-//          ran inside (each) VM. Maybe "using separate VMs" is a little
-// more clear.
-
-Containers work at the operating system level: packing the source code and its
-dependencies together, often with the entire environment required to run the
-application, while using the host system's kernel. This is what we call
-containers.
-// CSANAD:  I felt like some explanation like this on the term "container"
-//          was missing. Probably a simple hand-drawn image visualizing the
-// differences between virtualization and containerization could be also
-// helpful.
-
-They can give you multiple virtual operating systems that
+
+Containerization work at the operating system level:
+it gives you multiple virtual operating systems that
 all run on a single real OS.
+It lets us pack the source code and its dependencies together,
+the entire environment required to run the application.
 So you can run programs inside separate virtual environments,
 using a single real host operating system and kernel.
-// CSANAD:  rephrased it a little, since containers aren't necessarily
-//          separate operating systems. Sometimes they are just a few
-// processes running in isolation. This, in my opinion aligns better
-// with the way Docker worded it.
-For further clarification, have a look at
-https://www.docker.com/resources/what-container/[Docker's Resources on
-containers]
-
-The upshot of this is that containers are much "cheaper" in terms of
-system resources.
-// CSANAD:  probably nobody would believe you were talking about
-//          money, but I think it's more specific this way.
+
+Have a look at
+https://www.docker.com/resources/what-container/[Docker's resources on containers]
+for more explanation,
+The upshot of this is that containers are much "cheaper".
 You can start one up in milliseconds,
 and you can run hundreds on the same machine.
 
@@ -219,15 +203,9 @@ How will containerizing our software help with the danger areas?
 
 * We can use the containers to package up as much
   of the functionality of our application as possible,
-  which in turn will minimise the amount of configuration
+  like a production-ready web server and static files system.
+  This in turn will minimise the amount of configuration
   we need to do to our actual servers.
-// CSANAD:  I'm not sure about this point. Can you be a bit more
-//          specific or maybe give a few examples?
-// I feel like the first point is about having the dependencies along
-// with the source code and setting open ports, users set up for running
-// the program, DB-related settings, etc. This one is a little vague,
-// I'm not sure what functionalities would save additional configuration
-// of the servers.
 
 * We can test our containers work by running our functional tests
   against them.
@@ -240,6 +218,7 @@ How will containerizing our software help with the danger areas?
   minimised the risk of deployment to production.
 
 // TODO: consider getting rid of the staging server??
+// CSANAD:  I would keep the staging server.
 
 ////
 
@@ -251,8 +230,6 @@ But there are solutions to all of these.  In order:
 *   Using a 'staging site', on the same infrastructure as the production site,
     can help us test out our deployments and get things right before we go to
     the "real" site.
-// CSANAD:  I would keep the staging server.
-
 
 *   We can also 'run our functional tests against the staging site'. That will
     reassure us that we have the right code and packages on the server, and
@@ -264,12 +241,6 @@ But there are solutions to all of these.  In order:
     like on our own PC, a 'virtualenv' is useful on the server for
     managing packages and dependencies when you might be running more than one
     Python [keep-together]#application#.
-// CSANAD:  I would keep virtualenv in containers. First, because it doesn't hurt and
-//          I have no knowledge of it resulting in any overhead. Second, because pip warns
-// against globally installed packages, and ignoring warnings is bad.
-// Finally, because it "feels" right:
-// my application is set up so that if I decide to switch over from containers to VM-s, I
-// don't really need to touch dependency management.
 
 *   ((("automated deployment", "benefits of")))((("automated deployment", see="also Fabric")))And
     finally, 'automation, automation, automation'.  By using an automated
@@ -280,7 +251,6 @@ But there are solutions to all of these.  In order:
     "preproduction" servers.  Whatever we call it, the point is to have
     somewhere we can try our code out in an environment that's as similar as
     possible to the real production server.]
-
 ////
 
 
@@ -337,7 +307,6 @@ and where testing fits in.
 
 * Confidently deploy to production once we have a working deployment script for staging.
 
-// CSANAD:  the last two points were in reverse order
 
 
 === As Always, Start with a Test
@@ -536,9 +505,7 @@ 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 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.
+so I decided to stick with it. But you could definitely check it out!
 
 You can follow along all the instructions in the book
 by just substituing the `docker` binary for `podman` in all the CLI instructions,
@@ -577,13 +544,11 @@ What do we need to do?  Something like this, right?
 4. Run `python manage.py runserver`
 
 
+We create a new file called _Dockerfile_ in the base folder of our repo,
+next to the `src/` directory we made earlier:
+
 .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>
@@ -623,7 +588,7 @@ CMD python manage.py runserver  <4>
 
 
 
-==== Docker build
+==== Docker Build
 
 You build an image with `docker build <path-containing-dockerfile>`
 and we'll use the `-t <tagname>` argument to "tag" our image
@@ -667,8 +632,7 @@ superlists    latest    7b8e1c9fa68e   13 minutes ago   155MB
 
 
 
-==== Docker run
-
+==== Docker Run
 
 Once you've built an image,
 you can run one or more containers based on that image, using `docker run`.
@@ -819,20 +783,12 @@ CMD python manage.py runserver
 
 TIP: Forgetting the `-r` and running `pip install requirements.txt`
     is such a common error, that I recommend you do it _right now_
-    and get familiar with the error message,
-    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
-
+    and get familiar with the error message
+    (which is thankfully much more helpful than it used to be).
+    It's a mistake I still make, _all the time_.
 
 
-==== Successful run
+==== Successful Run
 
 Let's do the `build` and `run` in a single line.
 This is a pattern I used quite often when developing a Dockerfile,
@@ -881,14 +837,40 @@ 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`.
+    See <<how-to-stop-a-docker-container>> for an escape hatch.
+
+
+[[how-to-stop-a-docker-container]]
+.How to Stop a Docker Container
+*******************************************************************************
+If you've got a container that's "hanging" in a terminal window,
+you can kill it from another one.
+
+The docker daemon lets you list all the currently running containers
+with `docker ps`:
+
+[role="skipme small-code"]
+----
+$ *docker ps
+CONTAINER ID   IMAGE        COMMAND                  CREATED         STATUS         PORTS     NAMES
+0818e1b8e9bf   superlists   "/bin/sh -c 'python …"   4 seconds ago   Up 4 seconds             hardcore_moore
+----
+
+This tells us a bit about each container, including a unique ID,
+and a randomly-generated name (you can override that if you want to).
+
+We can use the ID or the name to kill the container with `docker kill`:
+
+[role="skipme"]
+----
+$ docker kill 0818e1b8e9bf
+0818e1b8e9bf
+----
+
+And if you go back to your other terminal window,
+you should find the docker process has been terminated.
+
+*******************************************************************************
 
 
 
@@ -913,17 +895,14 @@ 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. Let's visit http://localhost:8888/:
+First let's try and take a look ourselves, in our browser, by going to 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:
+Now let's take another look at the output from our `docker run`.
+Here's what appeared right at the end:
 
 
 [role="skipme"]
@@ -934,8 +913,6 @@ Quit the server with CONTROL-C.
 
 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:
 
@@ -952,7 +929,7 @@ CMD python manage.py runserver 8888
 ====
 
 Ctrl+C the current dockerized container process if it's still running in your terminal,
-give it another `build && run`:
+then give it another `build && run`:
 
 [subs="specialcharacters,quotes"]
 ----
@@ -962,9 +939,9 @@ Starting development server at http://127.0.0.1:8888/
 ----
 
 
-==== Debugging web server connectivity with "curl"
+==== Debugging Web Server Connectivity With "curl"
 
-Nope, that won't work either.
+A quick check in our browser will show us that nope, that doesn't work either.
 Let's try an even lower-level smoke test, the traditional Unix utility `curl`.
 It's a command-line tool for making HTTP requests.  Try it on your own computer first:
 
@@ -1063,7 +1040,7 @@ That's definitely some HTML! And the `<title>To-Do lists</title>` looks like it'
 So, we can see Django is serving our site _inside_ the container,
 why can't we see it _outside_??
 
-==== Exposing Docker Ports
+==== Docker Ports Mapping
 
 The pythonspeed guide to Docker's very first section is called
 https://pythonspeed.com/articles/docker-connection-refused/[Connection Refused],
@@ -1076,9 +1053,6 @@ from the ports _outside_ the container, the ones we can see on our host machine.
 
 So we need to tell Docker to connect the internal ports to the outside ones,
 to "publish" or "map" them, in Docker terminology.
-// CSANAD:  "expose" is different, it's for inter-container communication and it's
-//          done by the EXPOSE instruction in the Dockerfile. The -p is short for
-// --publish and this is port mapping.
 
 `docker run` takes a `-p` argument, with the syntax `OUTSIDE:INSIDE`.
 So you can actually map a different port number on the inside and outside.
@@ -1120,6 +1094,7 @@ curl: (52) Empty reply from server
 // Hopefully, just like above, the difference is irrelevantr but somebody please
 // confirm.
 
+
 ==== Essential Googling the Error Message
 
 The need to map ports and the `-p` argument to `docker run` are something you just learn,
@@ -1226,8 +1201,6 @@ A quick visual inspection confirms--the site is up (<<site-in-docker-is-up>>)!
 [[site-in-docker-is-up]]
 .The site in Docker is up!
 image::images/twp2_0903.png["The front page of the site, at least, is up"]
-// CSANAD:  This isn't the staging site yet! These screenshots and some of the text
-//          seems to be not updated.
 
 
 Let's see what our functional tests say:
@@ -1316,9 +1289,6 @@ RUN python manage.py migrate --noinput  <1>
 CMD python manage.py runserver
 ----
 ====
-// CSANAD:  I prefer specifying the path (/venv/bin/python) too, but we already set the PATH to in-
-//          clude /venv/bin and also, we haven't been using this explicit path in the Dockerfile.
-// So, for the sake of consistency, I suggest removing it here as well.
 
 <1> We run `migrate` using the `--noinput` argument to suppress any little "are you sure" prompts.
 
@@ -1389,7 +1359,15 @@ $ *docker build -t superlists . && docker run \
   -it superlists*
 ----
 
-//CSANAD: sessions.0001_initial is the last migration on the last line, removed `[...]`
+////
+footgun: if you don't have db.sqlite3
+
+docker: Error response from daemon: error while creating mount source path '/Users/harry.percival/workspace/Book-TDD-Web-Dev-Python/source/chapter_09_docker/superlists/src/db.sqlite3': chown /Users/harry.percival/workspace/Book-TDD-Web-Dev-Python/source/chapter_09_docker/superlists/src/db.sqlite3: permission denied.
+ERRO[0000] error waiting for container: context canceled
+
+❯ ls src/db.sqlite3/
+////
+
 
 TIP: if you see an error saying: `django.db.utils.OperationalError`: "unable to open database file",
     try stopping the container, `rm -rf src/db.sqlite3`, then re-run the migrate command