Rita edits to ch 9

Author: ritaf-ORM

chapter_09_docker.asciidoc

@@ -1,5 +1,6 @@
 [[chapter_09_docker]]
 == Deployment Part 1: 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. 
 
 [quote, 'http://bit.ly/2uhCXnH[Devops Borat]']
 ______________________________________________________________
@@ -97,7 +98,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:[
@@ -109,8 +110,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,
@@ -134,7 +135,7 @@ sometimes referred to as "containerization".
 You may have already heard of the idea of "virtualization",
 which allows a single physical computer to pretend to be several machines.
 Pioneered by IBM (amongst others) on mainframes in the 1960s,
-it rose to mainstream adoption in the 90s,
+it rose to mainstream adoption in the 1990s,
 where it was sold as a way to optimise resource usage in datacentres.
 AWS, for example, was an offshoot of Amazon,
 who were using virtualization already,
@@ -143,46 +144,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
@@ -257,7 +258,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,
@@ -280,7 +281,7 @@ and where testing fits in.
 
 
 
-
+//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
@@ -292,7 +293,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.
@@ -354,8 +355,8 @@ 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,
+// RITA: In the next three chapters or the chapters in the book as a whole?
+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,
@@ -481,7 +482,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
@@ -497,7 +498,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.
@@ -576,10 +577,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.
@@ -723,7 +724,7 @@ $ *git commit -m "Add requirements.txt for virtualenv"*
 You may be wondering why we didn't add our other dependency,
 Selenium, to our requirements,
 or why we didn't just add _all_ the dependencies,
-including the "transitive" ones (eg, Django has its own dependencies of `asgiref` and `sqlparse`).
+including the "transitive" ones (e.g., Django has its own dependencies of `asgiref` and `sqlparse`).
 
 As always, I have to gloss over some nuance and tradeoffs,
 but the short answer is first, Selenium is only a dependency for the tests,
@@ -734,7 +735,7 @@ in more tools, and I didn't want to do that for this book.footnote:[
 When you have a moment, you might want to do some further reading
 on "lockfiles", pyproject.toml, hard pinning vs soft pining,
 and immediate vs transitive dependencies.  If I absolutely _had_
-to recommend a python dependency management tool,
+to recommend a Python dependency management tool,
 it would be https://github.com/jazzband/pip-tools[pip-tools],
 which is a fairly minimal one.]
 
@@ -791,8 +792,8 @@ TIP: Forgetting the `-r` and running `pip install requirements.txt`
 ==== 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,
-to be able to quickly rebuild and see the effect of a change:
+This is a pattern I used quite often when developing a Dockerfile so I can
+quickly rebuild and see the effect of a change:
 
 [subs="specialcharacters,quotes"]
 ----
@@ -876,7 +877,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"]
@@ -889,13 +890,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
@@ -927,7 +928,7 @@ WORKDIR /src
 CMD python manage.py runserver 8888
 ----
 ====
-
+//RITA: Newbie question. What does Ctrl+C do again? Add a couple of words to give us some quick context. "Use Ctrl+C to kill the current..."
 Ctrl+C the current dockerized container process if it's still running in your terminal,
 then give it another `build && run`:
 
@@ -1066,6 +1067,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"]
@@ -1150,7 +1152,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"]
 ----
@@ -1179,7 +1181,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,
@@ -1268,7 +1270,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.
@@ -1324,6 +1326,7 @@ 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).
+//RITA: If you're going to be funny with a (TM), then I suggest you take it further by using caps for the term. "A Very Useful Thing to Be Able to Do (TM)."
 
 
 First let's revert our change:
@@ -1369,7 +1372,7 @@ ERRO[0000] error waiting for container: context canceled
 ////
 
 
-TIP: if you see an error saying: `django.db.utils.OperationalError`: "unable to open database file",
+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
     _outside_ the container, and then rebuild and run your image.
 
@@ -1391,7 +1394,8 @@ Ran 3 tests in 26.965s
 OK
 ----
 
-AMAZING IT ACTUALLY WORKSSSSSSSS.
+//RITA: I'd rather add exclamation marks than extend the word.
+AMAZING! IT ACTUALLY WORKS!
 
 Ahem, that's definitely good enough for now!  Let's commit.
 
@@ -1408,7 +1412,7 @@ but now we can be reassured that the basic Docker plumbing works.
 Notice that the FT was able to guide us incrementally towards a working config,
 and spot problems early on (like the missing database).
 
-But we really can't be using the Django dev server in production,
+However, we really can't be using the Django dev server in production,
 or running on port 8888 forever.
 In the next chapter, we'll make our hacky image more production-ready.