some polishing in docker chaps

Author: hjwp

chapter_09_docker.asciidoc

@@ -189,8 +189,6 @@ and most of the rest of the deployment process is taken care of by someone else.
 
 === Docker and the Danger Areas of Deployment
 
-// TODO: expand this section, is just bullet points atm
-
 How will containerizing our software help with the danger areas?
 
 * Containers are like a little virtual server,
@@ -263,11 +261,11 @@ But there are solutions to all of these.  In order:
 
 === An Overview of Our Deployment Procedure
 
-Over the next few pages I'm going to go through _a_ deployment procedure.
+Over these three chapters 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,
-to show the kinds of issues involved in deployment,
+to show the kinds of issues involved in putting code into production,
 and where testing fits in.
 
 
@@ -290,11 +288,11 @@ and where testing fits in.
 **Next chapter: moving to a production-ready configuration**
 
 * Gradually, incrementally change the container configuration
-  to make it production-ready,
+  to make it production-ready.
 
 * Regularly re-run the FTs to check we didn't break anything.
 
-* Address issues to do with the database, static files, etc.
+* Address issues to do with the database, static files, and so on.
 
 // gunicorn, DEBUG=False, secret key, etc
 
@@ -314,12 +312,6 @@ and where testing fits in.
 * We'll use Ansible to build an automated script that can deploy
   our container to staging
 
-NOTE: A clarification: in these chapter,
-    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.
-
 
 === As Always, Start with a Test
 
@@ -367,6 +359,14 @@ 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 chapter,
+    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.
+
+
 We test that said hack hasn't broken anything by running the functional
 tests [keep-together]#"normally"#:
 
@@ -455,7 +455,7 @@ Currently, all our code is source code really, so we move everything into _src_
 (we'll be seeing some new files appearing outside _src_ shortly.footnote:[
 A common thing to find outside of the _src_ folder is a folder called _tests_.
 We won't be doing that while we're relying on the standard Django test framework,
-but it's a common thing to do if you're using pytest, for example.]
+but it's a good thing to do if you're using pytest, for example.]
 )
 
 
@@ -464,7 +464,7 @@ but it's a common thing to do if you're using pytest, for example.]
 [subs="specialcharacters,quotes"]
 ----
 $ *mkdir src*
-$ *git mv * src*
+$ *git mv functional_tests lists superlists manage.py src*
 $ *git commit -m "Move all our code into a src folder"*
 ----
 
@@ -497,6 +497,7 @@ What's happened there is that Docker has
 
 Cool! We'll find out more about all of these steps as the chapter progresses.
 
+
 .Podman, a Docker Alternative
 *****************************************************************************************
 Impartiality commands me to also recommend https://podman.io/[Podman],
@@ -510,7 +511,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 didn't decide to switch. But you could definitely check it out!
+so I didn't decide to stick with Docker. 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,
@@ -1151,8 +1152,6 @@ It always seems hopeless at first!  But eventually you get there.
 
 === Database migrations
 
-// TODO:  these errors won't happen if the user has run "migrate" on their own machine.
-
 ((("database migrations")))
 A quick visual inspection confirms--the site is up (<<staging-is-up>>)!
 
@@ -1224,12 +1223,10 @@ Run 'python manage.py migrate' to apply them.
 
 
 NOTE: If you don't see this error,
-    it's because your source repo already had the database file in it, unlike mine.
+    it's because your src folder had the database file in it, unlike mine.
     For the sake of argument, run `rm src/db.sqlite` and re-run the build & run commands,
     and you should be able to repro the error.  I promise it's instructive!
 
-// TODO this ^ is hacky. figure out a way to make it more likely that the user sees the error.
-
 
 ==== Should we run "migrate" inside the Dockerfile? No.
 
@@ -1339,9 +1336,9 @@ Ran 3 tests in 26.965s
 OK
 ----
 
-AMAZING IT ACTUALLY WORKS
+AMAZING IT ACTUALLY WORKSSSSSSSS.
 
-That's definitely good enough for now!  Let's commit.
+Ahem, that's definitely good enough for now!  Let's commit.
 
 
 [subs="specialcharacters,quotes"]
@@ -1351,26 +1348,22 @@ $ *git commit -m"First cut of a Dockerfile"*
 ----
 
 
-Time for a well-earned tea break I think, and perhaps a
-https://en.wikipedia.org/wiki/Digestive_biscuit[chocolate biscuit].
-
-
-Success!  Our Hack Deployment Works
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Phew.  Well, it took a bit of hacking about,
 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.
+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,
 or running on port 8888 forever.
 In the next chapter, we'll make our hacky image more production-ready.
 
+But first, time for a well-earned tea break I think, and perhaps a
+https://en.wikipedia.org/wiki/Digestive_biscuit[chocolate biscuit].
+
 
 .Test-Driving Server Configuration and Deployment
 *******************************************************************************
 
-
 TODO update this recap.
 
 
@@ -1389,10 +1382,5 @@ Some typical pain points--networking, ports, static files, and the database::
     production.  You'll need to think through each of these for your own
     deployments.
 
-Tests allow us to experiment and work incrementally::
-    Whenever we make a change to our server configuration, we can rerun the
-    test suite, and be confident that everything works as well as it did
-    before.  It allows us to experiment with our setup with less fear (as
-    we'll see in the next chapter).
 
 *******************************************************************************