Merge pull request #276 from hjwp/ch17

Chapter 17 minimal update

Author: hjwp

chapter_11_ansible.asciidoc

@@ -642,6 +642,10 @@ In Ansible config, it looks like this:
 ----
 ====
 
+NOTE: Colima users on MacOS may need to set an env var to get the ansible-docker
+    integration to work in the "Export container image locally" stage:
+    `DOCKER_HOST=unix:///$HOME/.colima/default/docker.sock`
+
 // CSANAD: I would add `update_cache: true` to the `Install docker` task back,
 //         it's a good practice to update the apt cache before installing.
 //

chapter_17_second_deploy.asciidoc

@@ -1,69 +1,106 @@
 [[chapter_17_second_deploy]]
-Deploying Our New Code
-----------------------
+== Deploying Our New Code
 
-((("deployment", "procedure for", id="Dpro17")))It's
-time to deploy our brilliant new validation code to our live servers.
+((("deployment", "procedure for", id="Dpro17")))
+It's time to deploy our brilliant new validation code to our live servers.
 This will be a chance to see our automated deploy scripts in action for the
 second time.
 
+NOTE: At this point I always want to say a huge thanks to Andrew Godwin
+    and the whole Django team.
+    Up until Django 1.7, I used to have a whole long section,
+    entirely devoted to migrations.
+    Migrations now "just work", so I was able to drop it altogether.
+    I mean yes this all happened nearly ten years ago,
+    but still--open source software is a gift.
+    We get such amazing things, entirely for free.
+    It's worth taking a moment to be grateful, now and again.
 
-NOTE: At this point I want to say a huge thanks to Andrew Godwin and the whole
-    Django team.  Up until Django 1.7, I used to have a whole long section,
-    entirely devoted to migrations.  Migrations now "just work", so I was able to
-    drop it altogether.  Thanks for all the great work, gang!
 
-
-.🚧 Warning, Content not updated
+.🚧 Warning, Under construction
 *******************************************************************************
 
-This chapter has not been rewritten as part of the third edition.
+This chapter has only just been rewritten as part of the third edition.
+Please send feedback!
 
-By all means refer back to <<chapter_11_ansible>>
-and try and do a deployment,
-but otherwise, go ahead and check out <<chapter_18_spiking_custom_au,the next chapter>>, which has been (mostly) updated.
+You can refer back to <<chapter_11_ansible>> for reminders on Ansible commands.
 
 *******************************************************************************
 
 
-Staging Deploy
-~~~~~~~~~~~~~~
+=== Staging Deploy
 
 
 We start with the staging server:
 
-[role="against-server"]
+[role="against-server small-code"]
 [subs="specialcharacters,macros"]
 ----
-$ pass:quotes[*git push*]
-$ pass:quotes[*cd deploy_tools*]
-$ pass:quotes[*fab deploy:[email protected]*]
+$ pass:quotes[*ansible-playbook --user=elspeth -i staging.ottg.co.uk, infra/ansible-provision.yaml -vv*]
 [...]
-Disconnecting from staging.ottg.co.uk... done.
-----
 
-Restart Gunicorn:
+PLAYBOOK: ansible-provision.yaml ***********************************************
+1 plays in infra/ansible-provision.yaml
 
-[role="server-commands skipme"]
-[subs="specialcharacters,quotes"]
-----
-elspeth@server:$ *sudo systemctl restart gunicorn-staging.ottg.co.uk*
+PLAY [all] *********************************************************************
+
+TASK [Gathering Facts] *********************************************************
+[...]
+ok: [staging.ottg.co.uk]
+
+TASK [Install docker] **********************************************************
+[...]
+ok: [staging.ottg.co.uk] => {"cache_update_time": [...]
+
+TASK [Build container image locally] *******************************************
+[...]
+ok: [staging.ottg.co.uk -> 127.0.0.1] => {"actions": ["Built image superlists:latest [...]
+
+TASK [Export container image locally] ******************************************
+ok: [staging.ottg.co.uk -> 127.0.0.1] => {"actions": [], "changed": false, "image": [...]
+
+TASK [Upload image to server] **************************************************
+ok: [staging.ottg.co.uk] => {"changed": false, "checksum": [...]
+
+TASK [Import container image on server] ****************************************
+ok: [staging.ottg.co.uk] => {"actions": ["Loaded image superlists:latest [...]
+
+TASK [Ensure .env file exists] *************************************************
+ok: [staging.ottg.co.uk] => {"changed": false, "dest": "/home/elspeth/superlists.env", [...]
+
+TASK [Ensure db.sqlite3 file exists outside container] *************************
+changed: [staging.ottg.co.uk] => {"changed": true, "dest": "/home/elspeth/db.sqlite3", [...]
+
+TASK [Run container] ***********************************************************
+changed: [staging.ottg.co.uk] => {"changed": true, "container": [...]
+
+TASK [Run migration inside container] ******************************************
+changed: [staging.ottg.co.uk] => {"changed": true, "rc": 0, "stderr": "", [...]
+
+PLAY RECAP *********************************************************************
+staging.ottg.co.uk         : ok=10   changed=3    unreachable=0    failed=0
+skipped=0    rescued=0    ignored=0
+[...]
+Disconnecting from staging.ottg.co.uk... done.
 ----
 
+
 And run the tests against staging:
 
 [role="small-code"]
 [subs="specialcharacters,macros"]
 ----
-$ pass:quotes[*STAGING_SERVER=staging.ottg.co.uk python manage.py test functional_tests*]
+$ pass:quotes[*TEST_SERVER=staging.ottg.co.uk python src/manage.py test functional_tests*]
 OK
 ----
 
 
+Hooray!
+
+
 
 [role="pagebreak-before less_space"]
-Live Deploy
-~~~~~~~~~~~
+=== Live Deploy
 
 
 Assuming all is well, we then run our deploy against live:
@@ -72,33 +109,39 @@ Assuming all is well, we then run our deploy against live:
 [role="against-server"]
 [subs="specialcharacters,macros"]
 ----
-$ pass:quotes[*fab deploy:host=elspeth@superlists.ottg.co.uk*]
+$ pass:quotes[*ansible-playbook --user=elspeth -i www.ottg.co.uk, infra/ansible-provision.yaml -vv*]
 ----
 
-[role="server-commands"]
-[subs="specialcharacters,quotes"]
-----
-elspeth@server:$ *sudo service gunicorn-superlists.ottg.co.uk restart*
-----
 
 
-What to Do If You See a Database Error
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== What to Do If You See a Database Error
 
 
 Because our migrations introduce a new integrity constraint, you may find
 that it fails to apply because some existing data violates that constraint.
 
 At this point you have two choices:
 
-* Delete the database on the server and try again.  After all, it's only a 
-  toy project!
+1. Delete the database on the server and try again.
+  After all, it's only a toy project!
+
+2. Learn about data migrations.  See <<data-migrations-appendix>>.
+
+
+Here's how you might do option (1):
+
+[role="skipme"]
+----
+ssh [email protected] rm db.sqlite3
+----
+
+The `ssh` command takes an arbitrary shell command to run as its last argument,
+so we pass in `rm db.sqlite3`.
+We don't need a full path because we keep the sqlite database in elspeth's home folder.
 
-* Learn about data migrations.  See <<data-migrations-appendix>>.
 
 
-Wrap-Up: git tag the New Release
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Wrap-Up: git tag the New Release
 
 
 The last thing to do is to tag the release in our VCS--it's important that
@@ -125,8 +168,8 @@ topics that comprise <<part3>>.  Can't wait!
 
 We've done a couple of deploys now, so this is a good time for a little recap:
 
-* `git push` latest code
-* Deploy to staging and run functional tests against staging
+* Deploy to staging first
+* Run our FTs against staging.
 * Deploy to live
 * Tag the release