start getting 11 into shape

Author: hjwp

chapter_09_docker.asciidoc

@@ -213,13 +213,6 @@ How will containerizing our software help with the danger areas?
 // TODO: consider getting rid of the staging server??
 
 
-////
-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.]
-////
 
 ////
 

chapter_11_ansible.asciidoc

@@ -1,5 +1,5 @@
 [[chapter_11_ansible]]
-== Infrastructure As Code with Ansbile
+== Infrastructure As Code: Automated Deployments With Ansbile
 
 [quote, 'Cay Horstman']
 ______________________________________________________________
@@ -17,13 +17,17 @@ but a key insight of the modern infrastructure management
 is that automation really pays off in reducing maintenance burdens.
 
 It's also key to making sure our tests give us true confidence over our deployments.
-If we go to the trouble of builiding a staging server,
+If we go to the trouble of building a staging server,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.]
 we want to make sure that it's as similar as possible to the production environment.
 By automating the way we deploy, and using the same automation for staging and prod,
 we give ourselves much more confidence.
 
-The buzzword for automating your deployments these days is
-"Infrastructure as Code".
+The buzzword for automating your deployments these days is "Infrastructure as Code".
 
 NOTE: Why not ping me a note once your site is live on the web,
     and send me the URL?
@@ -101,7 +105,6 @@ but they broadly fall into two camps:
   offering like Heroku or my old employers, PythonAnywhere.
 
 
-
 ((("PythonAnywhere")))
 Particularly for small sites, a PaaS offers a lot of advantages,
 and I would definitely recommend looking into them.
@@ -113,9 +116,10 @@ doesn't necessarily tell you about the others.
 Any one of them might radically change their process or business model by the time you get to read this book.
 
 Instead, we'll learn just a tiny bit of good old-fashioned server admin,
-including SSH and manual server config.  They're unlikely to ever go away, and
-knowing a bit about them will get you some respect from all the grizzled
-dinosaurs out there.
+including SSH and manual server config.
+They're unlikely to ever go away,
+and knowing a bit about them will get you some respect
+from all the grizzled dinosaurs out there.
 
 
 
@@ -146,9 +150,9 @@ https://github.com/hjwp/Book-TDD-Web-Dev-Python/blob/master/server-quickstart.md
 
 NOTE: Some people get to this chapter, and are tempted to skip the domain bit,
     and the "getting a real server" bit, and just use a VM on their own PC.
-    Don't do this. It's 'not' the same, and you'll have more difficulty
-    following the instructions, which are complicated enough as it is.  If
-    you're worried about cost, have a look at the link above for free options.
+    Don't do this. It's _not_ the same, and you'll have more difficulty
+    following the instructions, which are complicated enough as it is.
+    If you're worried about cost, have a look at the link above for free options.
     ((("getting help")))
 
 
@@ -165,12 +169,12 @@ 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.
 
 
-
 .General Server Debugging Tips
 *******************************************************************************
 
-The most important lesson to remember from this chapter is to work
-incrementally, make one change at a time, and run your tests frequently.
+The most important lesson to remember from this chapter is,
+as always but more than ever, to work incrementally,
+make one change at a time, and run your tests frequently.
 
 When things (inevitably) go wrong, resist the temptation to flail about
 and make other unrelated changes in the hope that things will start working again;
@@ -183,11 +187,7 @@ It's just as easy to fall into the Refactoring-Cat trap on the server!
 
 
 
-
-
-
-Configuring Domains for Staging and Live
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+=== Configuring Domains for Staging and Live
 
 We don't want to be messing about with IP addresses all the time,
 so we should point our staging and live domains to the server.
@@ -213,16 +213,10 @@ so once you've set up your A-record,
 you can check its progress on a "propagation checking" service like this one:
 https://www.whatsmydns.net/#A/superlists-staging.ottg.eu.
 
-////
 I'm planning to host my staging server at 'superlists-staging.ottg.eu':
 
 
-NOTE: A clarification: in this chapter, we run tests 'against' our staging
-    server, not 'on' our staging server.  So we still run the tests from our
-    own laptop, but they target the site that's running on the server.
-////
-
-=== A first cut of an ansible script
+=== A first Cut of an Ansible Script
 
 Infrastructure-as-code tools, also called "configuration management" tools,
 come in lots of shapes and sizes.
@@ -231,8 +225,8 @@ and you'll probably come across Terraform,
 which is particularly strong on managing cloud services like AWS.
 
 We're going to use Ansible, because it's relatively popular,
-because I'm biased that it happens to be written in Python,
 because it can do everything we need it to,
+because I'm biased that it happens to be written in Python,
 and because it's probably the one I'm personally most familiar with.
 
 Another tool could probably have worked just as well!
@@ -243,7 +237,16 @@ rather than specifying a procedural series of steps to be followed one by one.
 
 
 Let's dip our toes into ansible,
-and see if we can get it to run a simple "hello world" container on our server:
+and see if we can get it to run a simple "hello world" container on our server.
+
+Here's what's called a "playbook" in ansible terminology.
+It's in a format called YAML (Yet Another Markup Language),
+which, if you've never come across before,
+you will soon develop a love-hatefootnote:[
+The "love" part is that yaml is very easy to _read_ and scan through at a glance.
+The "hate" part is that the actual syntax is surprisingly fiddly to get right:
+the difference between lists and key/value maps is subtle and I can never quite remember it honestly.]
+relationship with.
 
 
 [role="sourcecode"]
@@ -255,9 +258,9 @@ and see if we can get it to run a simple "hello world" container on our server:
 - hosts: all
 
   tasks:
-    - name: Install podman
-      ansible.builtin.apt:
-        name: podman
+    - name: Install podman  <1>
+      ansible.builtin.apt:  <2>
+        name: podman  <3>
         update_cache: yes
       become: true
 
@@ -270,12 +273,31 @@ and see if we can get it to run a simple "hello world" container on our server:
 ----
 ====
 
+<1> An ansible playbook is a series of "tasks"
+  (so in that sense it's still quite sequential and procedural),
+  but the individual tasks themselves are quite declarative.
+  Each one usually has a human-readable `name` attribute.
+
+<2> Each tasks uses an ansible "module" to do its work.
+  This one uses the `builtin.apt` module which provides
+  a wrapper around the `apt` Debian & Ubuntu package management tool.
+
+<3> Each module then provides a bunch of parameters which control
+  how it works.  Here we specify the `name` of the package we want to install ("docker")
+  and tell it update its cache first, which is required on a fresh server.
+
+Most ansible modules have pretty good documentation,
+check out the `builtin.apt` one for example.
+I often skip to the https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_module.html#examples[Examples section].
+
 [subs="specialcharacters,quotes"]
+
 ----
 $ *ansible-playbook --user=elspeth -i 192.168.56.10, infra/ansible-provision.yaml -vv*
 ----
 
-TODO show ansible output.
+TODO: show ansible output.
+TODO: stop using local ip 
 
 
 === SSHing Into the Server and Viewing Container Logs
@@ -479,7 +501,7 @@ Ansible and the podman plugins have some modules for this:
       containers.podman.podman_generate_systemd:
         name: superlists
         dest: ~/.config/systemd/user/
-    
+
     - name: Container must be started and enabled on systemd
       ansible.builtin.systemd:
         name: container-superlists