A bit of reordering in 9

Author: hjwp

chapter_09_docker.asciidoc

@@ -5,7 +5,7 @@
 ****
 With Early Release ebooks, you get books in their earliest form—the author's raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.
 
-This will be the 9th chapter of the final book. The GitHub repo is available at https://github.com/hjwp/book-example.
+This will be the 9th chapter of the final book. The GitHub repo is available at https://github.com/hjwp/book-example/tree/chapter_09_docker.
 
 If you have comments about how we might improve the content and/or examples in this book, or if you notice missing material within this chapter, please reach out to the author at [email protected].
 ****
@@ -51,11 +51,11 @@ on the actual internet.
 Give it a buzzword name like "DevOps"
 if that's what it takes to convince you it's worth it.
 
-.Warning, chapter under construction
+.New content alert!  Pls send feedback.
 ****
 As part of my work on the third edition of the book,
-I'm making big changes to the deployment chapters,
-and this is a very new draft.
+I've made big changes to the deployment chapters,
+so this stuff is all very fresh.
 
 What that means is that I'd, really, really love feedback from readers.
 Please have a go at following along and let me know what you think!
@@ -70,7 +70,7 @@ or if any of the instructions don't work for you.
 I hope you enjoy the new version!
 ****
 
-=== TDD and the Danger Areas of Deployment
+=== The Danger Areas of Deployment
 // XUAN: I read the title as meaning _TDD and_ the danger areas of deployment, but the following section seems to be talking about the danger areas of deployment?
 
 Deploying a site to a live web server can be a tricky topic.
@@ -107,6 +107,14 @@ Security and Configuration::
     become dangerous in production
     (because they expose our source code in tracebacks).
 
+Reproducibility and Divergence between local dev and prod::
+    All of the above add up to differences between your local development environemnt
+    and the way code runs in production.
+    We want to be able to reproduce the way things work on our machine,
+    as closely as possible, in production (and vice-versa)
+    to give us as much confidence as possible that
+    "it works on my machine" means "it's going to work in production".
+
 
 One way to approach the problem is to get a server
 and start manually configuring and installing everything,
@@ -126,6 +134,8 @@ before we actually take the plunge?
 Can we then make small changes one at a time,
 solving problems one by one,
 rather than having to bite off everything in one mouthful?
+Can we use our existing test suite to make sure things
+work on the server, as well as locally?
 
 Absolutely we can.  And from the title of the chapter,
 I'm sure you're already guessing that Docker is going
@@ -210,8 +220,8 @@ NOTE: If you're new to all this, I know it's a lot to wrap your head around!
   It takes a while to build a good mental model of what's happening.
   Have a look at
   https://www.docker.com/resources/what-container/[Docker's resources on containers]
-  for more explanation,
-  and hopefully, following along with these chapters and seeing them working in practice
+  for more explanation.
+  Hopefully, following along with these chapters and seeing them working in practice
   will help you to better understand the theory.
 
 
@@ -246,81 +256,16 @@ which, as always, is:
 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, 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
 (if you haven't already).
 For many working developers, a container image is the final artifact of their work,
 it's what they "deliver",
-and most of the rest of the deployment process is taken care of by someone else.
-
-
-=== Docker and the Danger Areas of Deployment
-
-How will containerizing our software help with the danger areas?
-// XUAN: I was expecting this section to give a brief high-level overview of how containerization can help address each one of the danger areas, but the following bullet points don't seem to do that
-
-* Containers can be like little virtual servers and this is how
-  we will use them,
-  so they will force us to address many of the problems
-  like dependency management and configuration.
-
-* We can use the containers to package up as much
-  of the functionality of our application as possible,
-  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.
-
-* We can test our containers work by running our functional tests
-  against them.
-
-* Later, when we deploy our containers to a staging server,
-  we can run the FTs against that too.
-// XUAN: "FTs" = "functional tests"?
-// XUAN: This is the first time this chapter mentions "staging", which seems a bit out of the blue. Can you elaborate on what problems does having a staging server solve for the initial list of danger areas of deployment?
-
-* If we automate container creation and deployment to staging,
-  and we've tested both those things, then we will have
-  minimised the risk of deployment to production.
-
-// TODO: consider getting rid of the staging server??
-// CSANAD:  I would keep the staging server.
-// SEBASTIAN: I second that.
-
-////
-
-old content follows. is there anything we want to rescue from here?
-
-But there are solutions to all of these.  In order:
-
-((("staging sites", "benefits of")))
-*   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.
-
-*   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
-    since we now have a "smoke test" for our site layout, we'll know that the
-    CSS is loaded correctly.
+and often the rest of the deployment process is something they rarely have to think about.
 
 
-*   ((("virtual environment (virtualenv)", "server-based")))Just
-    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#.
-
-*   ((("automated deployment", "benefits of")))((("automated deployment", see="also Fabric")))And
-    finally, 'automation, automation, automation'.  By using an automated
-    script to deploy new versions, and by using the same script to deploy to
-    staging and production, we can reassure ourselves that staging is as much
-    like live as possible.footnote:[What I'm calling a "staging" server, some people would
-    call a "development" server, and some others would also like to distinguish
-    "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.]
-////
-
 
 
 === An Overview of Our Deployment Procedure
@@ -355,7 +300,17 @@ and where testing fits in.
 * Address issues to do with the database, static files, secrets, and so on.
 
 
-**<<chapter_11_server_prep,Third chapter>>: Automating deployment to real servers**
+**<<chapter_11_server_prep,Third chapter>>: Preparing our staging server and deployment tools**
+
+* We'll set up a "staging":footnote:[
+Some people prefer the term pre-prod or test environment.
+It's all the same idea.]
+server, using the same infrastructure a we plan to use for production.
+* Set up a real domain name and point it at this server
+* Install Ansible and flush out any networking issues
+
+
+**<<chapter_12_ansible,Final chapter>>: Preparing our staging server and deployment tools**
 
 * Gradually build up an Ansible playbook to deploy our containers on a real server.
 
@@ -364,13 +319,39 @@ and where testing fits in.
 * Learn how to SSH in to the server to debug things,
   where to find logs and other useful information.
 
-* Use Ansible to build an automated script that can deploy
-  our container to staging.
-
 * Confidently deploy to production once we have a working deployment script for staging.
 
 
 
+=== TDD and Docker vs the Danger Areas of Deployment
+
+Hopefully you can start to see how the combination of TDD, Docker, Staging,
+and automation are going to help minimise the risk of the various "Danger Areas".
+
+* Containers will act as mini-servers
+  letting us flush out issues with dependencies, static files, and so on.
+  A key advantage is that they'll give us a way of getting faster feedback cycles,
+  because we can spin them up locally very quickly, and make changes quickly.
+
+* Our containers will package up both our Python and system dependencies,
+  including a production-ready web server and static files system.
+  as well as many production settings and configuration differences.
+  This minimises the difference between what we can test locally,
+  and what we will have on our servers.
+
+* Our FTs mean that we'll have a fully automated way of checking
+  that everything works.
+
+* Later, when we deploy our containers to a staging server,
+  we can run the FTs against that too.
+  It'll be slightly slower and might involve some fiddly compromises,
+  but it'll give us one more layer of reassurance.
+
+* Finally, by fully automating container creation and deployment,
+  and by testing the end results of both these things,
+  we maximise reproducibility, thus minimising the risk of deployment to production.
+
+
 === As Always, Start with a Test
 
 ((("environment variables")))