Merge pull request #222 from ritaf-ORM/patch-6

Rita edits ch 11

Author: hjwp

chapter_11_ansible.asciidoc

@@ -1,11 +1,12 @@
 [[chapter_11_ansible]]
-== Infrastructure As Code: Automated Deployments With Ansbile
+== Infrastructure As Code: Automated Deployments With Ansible
 
 [quote, 'Cay Horstman']
 ______________________________________________________________
 Automate, automate, automate.
 ______________________________________________________________
 
+// RITA: In this intro, please mention that you'll be using Ansible. Not only will it prep the reader, but it'll set you up to say "(or "become" in Ansible terminology)" in the User Accounts, SSH, and Privileges section before we actually get to the Ansible section.
 ((("deployment", "automating with Ansible", id="Dfarbric11")))
 ((("infrastructure as code")))
 In this chapter we're going to spin up an actual server,
@@ -27,12 +28,14 @@ we want to make sure that it's as similar as possible to the production environm
 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" (IaC).
+// RITA: OK to add the acronym IaC? It's common enough.
 
+// RITA: Perhaps move this to the It Worksss section so the reader sees it when their site actually goes live?
 NOTE: Why not ping me a note once your site is live on the web,
     and send me the URL?
     It always gives me a warm and fuzzy feeling...
-    [email protected].
+    Email me at [email protected].
 
 
 
@@ -43,7 +46,7 @@ I'm making big changes to the deployment chapters.
 This chapter is still very fresh, but the content is all there,
 so you should be able to follow along.
 
-But as always I really, really need fedback.
+But as always I really, really need feedback.
 So please hit me up at [email protected], or via
 https://github.com/hjwp/Book-TDD-Web-Dev-Python/issues[GitHub Issues]
 and Pull Requests.
@@ -122,7 +125,7 @@ from all the grizzled dinosaurs out there.
 
 ==== Spinning Up a Server
 
-I'm not going to dictate how you do this--whether
+I'm not going to dictate how you spin up a server--whether
 you choose Amazon AWS, Rackspace, Digital Ocean, your own server in a data centre,
 or a Raspberry Pi in a cupboard under the stairs,
 any solution should be fine, as long as:
@@ -150,21 +153,21 @@ NOTE: Some people get to this chapter, and are tempted to skip the domain bit,
     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.
+    If you're worried about cost, have a look at the guide I wrote for free options.
     ((("getting help")))
-
+// RITA: In general, please avoid saying above/below, as the final layout of the book will be determined later during Production. So, what's above now may end up on the previous page. It's better to reword it.
 
 ==== User Accounts, SSH, and Privileges
 
-In these instructions, I'm assuming that you have a nonroot user account set up,
+In the following instructions, I'm assuming that you have a nonroot user account set up,
 and that it has "sudo" privileges,
 so whenever we need to do something that requires root access, we use sudo,
 (or "become" in Ansible terminology),
 and I'm explicit about that in the various instructions that follow.
 
 My user is called "elspeth", but you can call yours whatever you like!
-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.
+Just remember to substitute it in all the places I've hardcoded it.
+See the guide I wrote if you need tips on creating a sudo user.
 
 
 .Security
@@ -258,10 +261,10 @@ rather than specifying a procedural series of steps to be followed one by one.
 
 ==== Installing Ansible
 
-Take a look at the instructions here:
-https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html
+Take a look at the  https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html [documentation] for instructions on how to install Ansible/
+// RITA: Please anchor all URLs to descriptive text.
 
-The simplest thing to do is to install them into the virtualenv
+The simplest thing to do is to install Ansible into the virtualenv
 on our local machine:
 
 [subs="specialcharacters,quotes"]
@@ -329,14 +332,14 @@ for.
 
 <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.
+    and tell it to 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].
 
-
+// RITA: Please add a sentence or two to introduce the following code block.
 [subs="specialcharacters,quotes"]
 ----
 $ *ansible-playbook --user=elspeth -i staging.ottg.co.uk, infra/ansible-provision.yaml -vv*
@@ -393,7 +396,7 @@ Ansible scripts are particularly satisfying in this regard.
 === SSHing Into the Server and Viewing Container Logs
 
 Time to get into some good old-fashioned sysadmin!
-Let's SSH in to our server and see if we can see any evidence that our container has run.
+Let's SSH into our server and see if we can see any evidence that our container has run.
 
 We use `docker ps -a` to view all containers, including old/stopped ones,
 and we can use `docker logs` to view the output from one of them:
@@ -443,10 +446,11 @@ and organisations will often run private ones,
 hosted by cloud providers like AWS.
 
 So your process of getting an image onto a server is usually
+
 * Push the image from your machine to the registry
 * Pull the image from the registry onto the server.
   Usually this step is implicit,
-  in that you just specifying the image name in the format registry-url/image-name:tag,
+  in that you just specify the image name in the format registry-url/image-name:tag,
   and then `docker run` takes care of pulling down the image for you.
 
 But I don't want to ask you to create a DockerHub account,
@@ -510,6 +514,7 @@ In Ansible config, it looks like this:
 <3> And we use `docker_image` again but this time with `load_path` and `source: load`
   to import the image back on the server
 
+// RITA: Please add a sentence or two to introduce the following code block.
 [subs="specialcharacters,quotes"]
 ----
 $ *ansible-playbook --user=elspeth -i staging.ottg.co.uk, infra/ansible-provision.yaml -vv*
@@ -592,7 +597,7 @@ This means we don't have a dependency on having run `docker build` locally.
   with compatibility between Apple's new ARM-based chips and our server's
   x86/amd64 architecture.
   You could also use this `platform:` to cross-build docker images
-  for a rasbperry pi from a regular PC, or vice-versa.
+  for a Rasberry Pi from a regular PC, or vice-versa.
   It does no harm in any case.
 
 
@@ -626,7 +631,7 @@ KeyError: 'DJANGO_SECRET_KEY'
 [2024-02-26 22:19:15 +0000] [1] [ERROR] Reason: Worker failed to boot.
 ----
 
-Ah woops, we need to set those environment variables on the server too.
+Whoops, we need to set those environment variables on the server too.
 
 
 === Using an env File to Store Our Environment Variables
@@ -636,8 +641,8 @@ But we don't want to hard-code secrets like SECRET_KEY into our Ansible files
 and commit them to our repo!
 
 Instead, we can use Ansible to automate the creation of a secret key,
-and then save it to a file on the server, where it _ill be _relatively_ secure
-(better than saving it to version control and pushing it to GitHub in any case!)
+and then save it to a file on the server, where it _will_ be _relatively_ secure
+(which is better than saving it to version control and pushing it to GitHub in any case!).
 
 We can use a so-called "env file" to store environment variables.
 Env files are essentially a list of key-value pairs using shell syntax,
@@ -652,7 +657,7 @@ So, just as we inject variables into our html templates in Django,
 we can use a templating language called "jinja2" to have variables in our env file.
 It's a common tool in Ansible scripts, and the syntax is very similar to Django's.
 
-Here's what our template for the env file will looks like:
+Here's what our template for the env file will look like:
 
 [role="sourcecode"]
 .infra/env.j2 (ch11l004)
@@ -704,7 +709,7 @@ And here's how we use it in the provisioning script:
 <3> The `vars` section defines the variables we'll inject into our template.
 
 <4> We actually use a built-in Ansible variable called `inventory_hostname`.
-    This variable woul actually be available in the template already,
+    This variable would actually be available in the template already,
     but I'm renaming it for clarity.
 
 <5> This `lookup('password')` thing I copy-pasted from Stackoverflow.
@@ -721,20 +726,20 @@ NOTE: Using an env file to store secrets is definitely better than committing
 .Idempotency and Declarative Configuration
 *******************************************************************************
 
-Infrastucture-as-code tools like Ansible aim to be "declarative",
+Infrastructure-as-code tools like Ansible aim to be "declarative",
 meaning that, as much as possible, you specify the desired state that you want,
 rather than specifying a series of steps to get there.
 
 This concept goes along with the idea of "idempotency",
 which is wanting to get the same result when you run something for the first time,
-vs running it again on later occations.
+vs running it again on later occasions.
 
 An example is the `apt` module that we used to install docker.
 It doesn't crash if docker is already installed, and in fact,
 Ansible is smart enough to check first before trying to install anything.
 
 There is some subtlety here, for example, our templated env file
-will only be writen once, so the step is idempotent in the sense
+will only be written once, so the step is idempotent in the sense
 that it doesn't overwrite the file with a new random secret key every time you run it.
 But that does come with the downside that you can't easily add new variables to the file.
 
@@ -874,7 +879,7 @@ on the server:
 ----
 ====
 
-That gets us to
+That gets us to:
 
 ----
 selenium.common.exceptions.NoSuchElementException: Message: Unable to locate
@@ -885,7 +890,7 @@ element: [id="id_list_table"]; [...]
 === Mounting the database on the server and running migrations
 
 Taking a look at the logs from the server,
-we can see that the database is not initialised.
+we can see that the database is not initialised:
 
 [subs="specialcharacters,quotes"]
 ----
@@ -913,7 +918,7 @@ staging.ottg.co.uk         : ok=9    changed=2    unreachable=0    failed=0
 skipped=0    rescued=0    ignored=0
 ----
 
-
+// RITA: Please expand this intro sentence. Here's how to do what?
 Here's how 
 
 [role="sourcecode"]
@@ -962,6 +967,8 @@ Here's how
 
 === It workssss
 
+// RITA: I'd prefer to call the section "It works!" with an exclamation point or two, but OK. Please expand the first sentence of the section to be more than just "Hooray." What was achieved? What does the following result indicate?
+
 Hooray
 
 [role="small-code"]
@@ -1003,7 +1010,7 @@ Docker into the mix, should things not go according to plan:
   This is a good place to go check on environment variables,
   port mappings, and exactly which image was running, for example.
 
-- And you can inspect the image with
+- You can inspect the image with
   `docker image inspect superlists`.
   You might need this to check the exact image hash,
   to make sure it's the same one you built locally.
@@ -1095,8 +1102,8 @@ $ *git log --graph --oneline --decorate*
 
 ////
 
-
-Anyway, you now have a live website!  Tell all your friends!
+// RITA: Perhaps add the note about the reader emailing you when their site goes live to this point. "Tell your mum! Tell me! Email me at....""
+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")))
 
@@ -1107,7 +1114,7 @@ And, in the next chapter, it's back to coding again.((("", startref="Fstage11"))
 ((("automated deployment", "additional resources")))
 There's no such thing as the One True Way in deployment;
 I've tried to set you off on a reasonably sane path,
-but there's plenty of things you could do differently,
+but there are plenty of things you could do differently,
 and lots, lots more to learn besides.
 Here are some resources I used for inspiration: