Merge rita's edits in 9

Author: hjwp

chapter_09_docker.asciidoc

@@ -1,5 +1,11 @@
 [[chapter_09_docker]]
-== Deployment Part 1: Containerization aka Docker
+== Containerization aka Docker
+// RITA: I'm not keen on including the word "part" in chapter titles
+// especially when the chapter is also within something called a "part."
+// Would it make sense to put the deployment chapters into its own Part?
+// So, ch8 might go into Part 1,
+// chs 9-11 would go into the new Part 2 called something like "Deployment,"
+// and Part 3 would start with ch 12. 
 
 .A Note for Early Release Readers
 ****
@@ -107,7 +113,7 @@ Security and Configuration::
     (because they expose our source code in tracebacks).
 
 
-One way to approach the problem is to get a server,
+One way to approach the problem is to get a server
 and start manually configuring and installing everything,
 hacking about until it works,
 and maybe think about automating things laterfootnote:[
@@ -119,8 +125,8 @@ in the world of agile/lean software development,
 it's that taking smaller steps usually pays off.
 
 How can we take smaller, safer steps towards a production deployment?
-Can we _simulate_ the process of moving to a server,
-so that we can iron out all the bugs,
+Can we _simulate_ the process of moving to a server
+so that we can iron out all the bugs
 before we actually take the plunge?
 Can we then make small changes one at a time,
 solving problems one by one,
@@ -153,46 +159,46 @@ to customers outside the business.
 
 So when you come to deploy your code to a real server in a datacentre,
 it will be using virtualization.
-And actually you can use virtualization on your own machine,
+And, actually, you can use virtualization on your own machine,
 with software like Virtualbox or KVM.
 
 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.
+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:
 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.
 
-Containerization work at the operating system level:
+Containerization works 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,
+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,
+This allows you to run programs inside separate virtual environments,
 using a single real host operating system and kernel.
 
 Have a look at
 https://www.docker.com/resources/what-container/[Docker's resources on containers]
-for more explanation,
+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.
 
 
 ==== Docker and your CV
 
-That's all well and good for the _theoretical_ justification.
-But let's get to the _real_ reason for using this technology,
+That's all well and good for the _theoretical_ justification,
+but let's get to the _real_ reason for using this technology,
 which, as always, is:
 "it's fashionable so it's going to look good on my CV."
 
 For the purposes of this book,
 that's not such a bad justification really!
 
-Yes I think it's going to be a nice way to have a "pretend"
+Yes, I think it's going to be a nice way to have a "pretend"
 deployment on our own machine, before we try the real one--but
 also, containers are so popular nowadays,
 that it's very likely that you're going to encounter them at work
@@ -267,7 +273,7 @@ But there are solutions to all of these.  In order:
 
 === An Overview of Our Deployment Procedure
 
-Over these three chapters, I'm going to go through _a_ deployment procedure.
+Over the next three chapters, I'm going to go through _a_ deployment procedure.
 It isn't meant to be the _perfect_ deployment procedure,
 so please don't take it as being best practice,
 or a recommendation--it's meant to be an illustration,
@@ -289,8 +295,7 @@ and where testing fits in.
   with passing tests.
 
 
-
-
+//RITA: Consider cross-referencing the chapter by number here so we can hyperlink it for convenience.
 **Next chapter: Moving to a production-ready configuration**
 
 * Gradually, incrementally change the container configuration
@@ -302,7 +307,7 @@ and where testing fits in.
 
 // gunicorn, DEBUG=False, secret key, etc
 
-
+//RITA: Consider cross-referencing the chapter by number here so we can hyperlink it for convenience.
 **Third chapter: Automating deployment to real servers**
 
 * Gradually build up an Ansible playbook to deploy our containers on a real server.
@@ -363,12 +368,11 @@ and to use a real server instead.
 <2> Here's the hack: we replace `self.live_server_url` with the address of
     our "real" server.
 
-
-NOTE: A clarification: in these chapters,
-    we run tests _against_ our Docker container, or _against_ our staging server,
-    but that doesn't mean we run the tests _from_ Docker or _from_ our staging server.
-    We still run the tests from our own laptop,
-    but they target the place that's running our code.
+NOTE: A clarification: when we say we run tests _against_ our Docker container,
+  or _against_ our staging server,
+  that doesn't mean we run the tests _from_ Docker or _from_ our staging server.
+  We still run the tests from our own laptop,
+  but they target the place that's running our code.
 
 
 We test that said hack hasn't broken anything by running the functional
@@ -489,7 +493,7 @@ Status: Downloaded newer image for busybox:latest
 hello world
 ----
 
-What's happened there is that Docker has
+What's happened there is that Docker has:
 
 * Searched for a local copy of the "busybox" image and not found it
 * Downloaded the image from DockerHub
@@ -505,7 +509,7 @@ Cool! We'll find out more about all of these steps as the chapter progresses.
 Impartiality commands me to also recommend https://podman.io/[Podman],
 which is a like-for-like replacement for Docker.
 
-It's pretty much exactly the same as docker,
+It's pretty much exactly the same as Docker,
 arguably with a few advantages even, but I won't go into detail here.
 
 I actually tried it out on early drafts of this chapter and it worked perfectly well.
@@ -585,10 +589,10 @@ CMD python manage.py runserver  <4>
 <2> The `COPY` instruction (the uppercase words are called "instructions")
     lets you copy files from your own computer into the container image.
     We use it to copy all our source code from the newly-created _src_ folder,
-    into a similarly-named folder at the root of the container image
+    into a similarly-named folder at the root of the container image.
 
 <3> `WORKDIR` sets the current working directory for all subsequent commands.
-     It's a bit like doing `cd /src`
+     It's a bit like doing `cd /src`.
 
 <4> Finally the `CMD` instruction tells docker which command you want it to run
     by default, when you start a container based on that image.
@@ -829,7 +833,7 @@ you should find the docker process has been terminated.
 
 === Using the FT to Check That Our Container Works
 
-Let's see what our FTs think about this Docker version of our site.
+Let's see what our FTs think about this Docker version of our site:
 
 
 [role="small-code"]
@@ -842,13 +846,13 @@ selenium.common.exceptions.WebDriverException: Message: Reached error page:
 about:neterror?e=connectionFailure&u=http%3A//localhost%3A8888/[...]
 ----
 
-Nope!  What's going on here?  Time for a little debugging.
+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, by going to 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
@@ -1019,6 +1023,7 @@ $ *docker build -t superlists . && docker run -p 8888:8888 -it superlists*
 Now that will _change_ the error we see, but only quite subtly (see <<firefox-connection-reset>>).
 Things clearly aren't working yet.
 
+//RITA: If at all possible, I suggest using the light or daytime theme for all browser screenshots to make them easier to read.
 [[firefox-connection-reset]]
 .Cannot connect on that port
 image::images/firefox-connection-reset.png["Firefox showing the 'Connection reset' error"]
@@ -1114,7 +1119,7 @@ $ *docker build -t superlists . && docker run -p 8888:8888 -it superlists*
 Starting development server at http://0.0.0.0:8888/
 ----
 
-We can verify it's working with `curl:
+We can verify it's working with `curl`:
 
 [subs="specialcharacters,macros"]
 ----
@@ -1143,7 +1148,7 @@ and say "well, this is hopeless, it can't be fixed",
 and give up.
 
 Thankfully I have had some good role models over the years
-who are much better at it than me (hi Glenn!).
+who are much better at it than me (hi, Glenn!).
 Debugging needs the patience and tenacity of a bloodhound.
 If at first you don't succeed,
 you need to systematically rule out options,
@@ -1232,7 +1237,7 @@ Run 'python manage.py migrate' to apply them.
 NOTE: If you don't see this error,
     it's because your src folder had the database file in it, unlike mine.
     For the sake of argument, run `rm src/db.sqlite3` and re-run the build & run commands,
-    and you should be able to repro the error.  I promise it's instructive!
+    and you should be able to reproduce the error.  I promise it's instructive!
 
 
 ==== Should we run "migrate" inside the Dockerfile? No.
@@ -1287,7 +1292,7 @@ For the purposes of this book, the easiest analogy to a server that's "outside"
 is to access the database from the filesystem outside the container.
 
 That also gives us a convenient excuse to talk about mounting files in Docker,
-which is a very useful thing to be able to do (TM).
+which is a very Useful Thing to be Able to Do (TM).
 
 
 First let's revert our change:
@@ -1365,6 +1370,7 @@ Ran 3 tests in 26.965s
 OK
 ----
 
+//RITA: I'd rather add exclamation marks than extend the word.
 AMAZING IT ACTUALLY WORKSSSSSSSS.
 
 Ahem, that's definitely good enough for now!  Let's commit.