Try and get chapter 11 ready for TR

Author: hjwp

chapter_11_ansible.asciidoc

@@ -167,6 +167,23 @@ Just remember to substitute it in all the places I've hardcoded it below.
 See the guide linked above if you need tips on creating a sudo user.
 
 
+.Security
+*******************************************************************************
+A serious discussion of server security is beyond the scope of this book,
+and I'd warn against running your own servers
+without learning a good bit more about it.
+(One reason people choose to use a PaaS to host their code
+is that it means a slightly fewer security issues to worry about.)
+If you'd like a place to start, here's as good a place as any:
+https://plusbryan.com/my-first-5-minutes-on-a-server-or-essential-security-for-linux-servers[My first 5 minutes on a server].
+I can definitely recommend the eye-opening experience of installing
+fail2ban and watching its logfiles to see just how quickly it picks up on
+random drive-by attempts to brute force your SSH login.  The internet is a
+wild place!
+((("security issues and settings", "server security")))
+((("Platform-As-A-Service (PaaS)")))
+*******************************************************************************
+
 ////
 
 TODO: good advice but not quite sure it's phrased quite right for the new version of the chapter.
@@ -1079,15 +1096,13 @@ $ *git log --graph --oneline --decorate*
 ////
 
 
-Anyway, you now have a live website!  Tell all your friends!  Tell your mum, if
-no one else is interested!  And, in the next chapter, it's back to coding
-again.((("", startref="Fstage11")))
-
+Anyway, you now have a live website!  Tell all your friends!
+Tell your mum, if no one else is interested!
+And, in the next chapter, it's back to coding again.((("", startref="Fstage11")))
 
 
-Further Reading
-~~~~~~~~~~~~~~~
 
+=== Further Reading
 
 ((("automated deployment", "additional resources")))
 There's no such thing as the One True Way in deployment;
@@ -1112,47 +1127,58 @@ Here are some resources I used for inspiration:
 .Automated Deployment Recap
 *******************************************************************************
 
-TODO Maybe recap the key steps of any deployment:
+Here's a brief recap of what we've been through,
+which are a fairly typical set of steps for deployment in general
+
+1. *Provisioning* a server. This tends to be vendor-specific,
+  so we didn't automate it, but you absolutely can!
+
+2. Installing *system dependencies* - in our case, it was mainly Docker,
+  but inside the Docker image, we also had some system dependencies too,
+  like Python itself.
+
+3. Getting our *application code* (or "artifacts") onto the server.
+  In our case, since we're using Docker, the thing we needed to transfer was a Docker image.
+  We used a manual process, but typically you'd push and pull to an image repository.
+
+4. Setting *environment variables and secrets*.
+  Depending on how you need to vary them,
+  you can set environment variables on your local PC,
+  in a Dockerfile, in your Ansible scripts, or on the server itself.
+  Figuring out which to use in which case is a big part of deployment.
 
-- installing docker (assuming that's the only system dep)
-- getting our image onto the server (normally just with docker push/pull)
-- setting env vars & secrets
-- attaching a database (a mounted file in our case)
-- configuring port
-- running migrations
-- and running or re-running the container
+5. Attaching to the *Database*. In our case we mount a file from the local filesystem.
+  More typically, you'd be supplying some environment variables and secrets to define
+  a host, port, username and password to use for accessing a database server.
 
-old content follows:
+6. Configuring *networking and port mapping*.  This includes DNS config,
+  as well as Docker configuration. Web apps need to be able to talk to the outside world!
+
+7. Running *Database migrations*.  We'll revisit this later in the book,
+  but migrations are one of the most risky part of a deployment,
+  and automating them is a key part of reducing that risk.
+
+8. *Switching across* to the new version of our application.
+  In our case, we stop the old container and start a new one.
+  In more advanced setups, you might be trying to achieve zero-downtime deploys,
+  and looking into techniques like red-green deployments.
+
+// TODO is there a better word than "switching across"?
+
+Every single aspect of deployment can and probably should be automated.
+Here are a couple of general principles to think about
+when implementing infrastructure-as-code:
 
 Idempotency::
   If your deployment script is deploying to existing servers,
-  you need to design them so that they work against a fresh installation 'and' against
+  you need to design them so that they work against a fresh installation _and_ against
   a server that's already configured.
   ((("idempotency")))
 
-Automating provisioning::
-  Ultimately, _everything_ should be automated, and that includes spinning up
-  brand new servers.
-  This will involve interacting with the API of your hosting provider.
+Declarative::
+  As much as possible, we want to try and specify _what_ we want the state to be on the server,
+  rather than _how_ we should get there.
+  This goes hand-in-hand with the idea of idempotency above.
 
-////
-
-TODO: find a place for this
-
-Security::
-  A serious discussion of server security is beyond the scope of this book,
-  and I'd warn against running your own servers
-  without learning a good bit more about it.
-  (One reason people choose to use a PaaS to host their code
-  is that it means a slightly fewer security issues to worry about.)
-  If you'd like a place to start, here's as good a place as any:
-  https://plusbryan.com/my-first-5-minutes-on-a-server-or-essential-security-for-linux-servers[My first 5 minutes on a server].
-  I can definitely recommend the eye-opening experience of installing
-  fail2ban and watching its logfiles to see just how quickly it picks up on
-  random drive-by attempts to brute force your SSH login.  The internet is a
-  wild place!
-  ((("security issues and settings", "server security")))
-  ((("Platform-As-A-Service (PaaS)")))
-////
 
 *******************************************************************************