Several fixes and address todos in 9. see #281

Author: hjwp

chapter_09_docker.asciidoc

@@ -156,29 +156,27 @@ So when you come to deploy your code to a real server in a datacentre,
 it will be using virtualization.
 And, actually, you can use virtualization on your own machine,
 with software like Virtualbox or KVM.
+You can run Windows "inside" a Mac or Linux laptop, for example.
 
-// SEBASTIAN: I'd consider giving a simple example, like:
-//      "Running virtualized Linux alongside Windows on your MacBook with MacOS? No problem!"
-//      Not sure how familiar new kids on the block are with virtualization, TBH.
-//      From the tone of paragraphs I have a feeling that readers' familiarity is assumed.
-//      While explanation of virtualization is great, I feel we lack relatable example.
-
-But that can be fiddly to set up!
+But it can be fiddly to set up!
 And nowadays, thanks to containerization, we can do better
 because containerization is a kind of even-more-virtual virtualization.
 
 Conceptually, "regular" virtualization works at the hardware level:
 it gives you multiple virtual machines (VMs)
-that pretend to be physical computers, on a single real machine.
+that pretend to be different physical computers, on a single real machine.
 So you can run multiple operating systems using separate VMs
 on the same physical box.
 
 Containerization works at the operating system level:
 it gives you multiple virtual operating systems that
 all run on a single real OS.
-It lets us pack the source code and its dependencies together--
-the entire environment required to run the application.
-This allows you to run programs inside separate virtual environments,
+(For this reason, containers tend to use the same operating
+system as the host OS.)
+
+Containers let us pack the source code and the system dependencies
+(like Python, or system libraries) together, 
+and our programs run inside separate virtual systems,
 using a single real host operating system and kernel.
 
 Have a look at
@@ -189,6 +187,26 @@ You can start one up in milliseconds,
 and you can run hundreds on the same machine.
 
 
+==== Why not just use a virtualenv?
+
+You might be thinking, this sounds a lot like a virtualenv,
+and you'd be right!
+Virtualenvs already let us run different versions of Python,
+with different Python packages, on the same machine.
+
+What Docker containers give us over and above virtualenvs,
+is the ability to have different _system_ dependencies too;
+things you can't `pip install`, in other words.
+In the Python world, this could be C libraries,
+like `libpq` for PostgreSQL, or `libxml2` for parsing XML.
+But you could also run totally different programming languages
+in different containers, or even different linux distributions.
+So, server administrators or platform people like them,
+because it's one system for running any kind of software,
+and they don't need to understand the intricacies of any particular
+language's packaging systems.
+
+
 ==== Docker and your CV
 
 That's all well and good for the _theoretical_ justification,
@@ -291,29 +309,21 @@ and where testing fits in.
 
 * Learn how to build and run a container on our machine.
 
-* Learn how to run our FTs against our container.
-
 * Get a first cut of our code up and running inside Docker,
   with passing tests.
 
-// DAVID: might be worth condensing this bulleted list, it's rather skimmable
-// at the moment. For example is there any difference between the first and fourth point?
 
-//RITA: Consider cross-referencing the chapter by number here so we can hyperlink it for convenience.
-
-**Next chapter: Moving to a production-ready configuration**
+**<<chapter_10_production_readiness,Next chapter>>: Moving to a production-ready configuration**
 
 * Gradually, incrementally change the container configuration
   to make it production-ready.
 
 * Regularly re-run the FTs to check we didn't break anything.
 
-* Address issues to do with the database, static files, and so on.
+* Address issues to do with the database, static files, secrets, and so on.
 
-// gunicorn, DEBUG=False, secret key, etc
 
-//RITA: Consider cross-referencing the chapter by number here so we can hyperlink it for convenience.
-**Third chapter: Automating deployment to real servers**
+**<<chapter_11_ansible,Third chapter>>: Automating deployment to real servers**
 
 * Gradually build up an Ansible playbook to deploy our containers on a real server.
 
@@ -358,6 +368,7 @@ class NewVisitorTest(StaticLiveServerTestCase):
             self.live_server_url = "http://" + test_server  #<2>
 ----
 ====
+
 // DAVID: could use a walrus operator here?
 
 Do you remember I said that `LiveServerTestCase` had certain limitations?
@@ -402,7 +413,7 @@ TIP: I'm deliberately choosing a different port to run Dockerised Django on (888
     we're looking at Docker, when we're actually looking at a local `runserver`
     that I've left running in some terminal somewhere.
 
-I'll use the `--failfast` option to exit as soon as a single test fails:
+We'll use the `--failfast` option to exit as soon as a single test fails:
 
 // CSANAD:  are line breaks necessary below and at other occurrences of
 //          --failfast? it does keep the asciidoc lines of source below 80
@@ -1061,6 +1072,8 @@ HTTP/1.1 200 OK
 </html>
 ----
 
+TIP:  Use `Ctrl+D` to exit from the `docker exec` bash shell inside the container.
+
 That's definitely some HTML! And the `<title>To-Do lists</title>` looks like it's our html, too.
 
 So, we can see Django is serving our site _inside_ the container,
@@ -1123,10 +1136,11 @@ $ pass:quotes[*curl -iv localhost:8888*]
 curl: (52) Empty reply from server
 ----
 
-// CSANAD:  I'm getting a different error for some reason:
-//          curl: (56) Recv failure: Connection reset by peer
-// Hopefully, just like above, the difference is irrelevantr but somebody please
-// confirm.
+NOTE: Depending on your system, instead of `(52) Empty reply from server`,
+  You might see `(56) Recv failure: Connection reset by peer`.
+  They mean the same thing.
+
+//TODO: double-check what the difference means here.
 
 
 ==== Essential Googling the Error Message
@@ -1321,7 +1335,11 @@ NOTE: If you don't see this error,
     and you should be able to reproduce the error.  I promise it's instructive!
 
 
-==== Should we run "migrate" inside the Dockerfile? No.  // JAN: Not sure I understand this line. You're saying that we shouldn't run migrate inside our Dockerfile, but then in the next line you do exactly that
+==== Should we run "migrate" inside the Dockerfile? No.
+
+// JAN: Not sure I understand this line.
+// You're saying that we shouldn't run migrate inside our Dockerfile,
+// but then in the next line you do exactly that
 
 So, should we include `manage.py migrate` in our Dockerfile?
 
@@ -1361,10 +1379,14 @@ Ran 3 tests in 26.965s
 OK
 ----
 
+The problem is that this saves our database image into our system image,
+which is not what we want,
+because the system image is mean to be something fixed and stateless,
+whereas the database is living, stateful data that should change over time.
+
 
 === Mounting files inside the container.
 
-But we don't actually want to package up our database _inside_ the image, do we?
 We want the database on the server to have totally separate data from the one on our machine.
 // CSANAD: we need to list `src/db.sqlite3` in the .dockerignore file to achieve this.
 //         Otherwise, if the reader did not delete the DB, it would still end up built into
@@ -1390,15 +1412,18 @@ First let's revert our change:
 [source,dockerfile]
 ----
 [...]
+COPY src /src
+
 WORKDIR /src
 
 CMD python manage.py runserver 0.0.0.0:8888
 ----
 ====
 
 
-Let's start by re-creating the database with `migrate`
-(when we moved everything into `./src`, we left the database file behind):
+Then let's make sure we _do_ have the database on our own machine,
+by running `migrate`:
+(when we moved everything into `./src`, we left the database file behind).
 
 [subs="specialcharacters,quotes"]
 ----
@@ -1411,14 +1436,18 @@ Running migrations:
   Applying sessions.0001_initial... OK
 ----
 
-Let's make sure to .gitignore the new location of the DB file:
+Let's make sure to _.gitignore_ the new location of the DB file,
+and we'll also use a file called https://docs.docker.com/reference/dockerfile/#dockerignore-file[_.dockerignore_]
+to make sure we can't copy our local dev database into our Docker image
+during Docker builds:
 
 [subs="specialcharacters,quotes"]
 ----
 $ *echo src/db.sqlite3 >> .gitignore*
+$ *echo src/db.sqlite3 >> .dockerignore*
 ----
 
-Now let's try mounting our database file.
+Now we can rebuild and try mounting our database file.
 The extra flag to add to the Docker run command is `--mount`,
 where we specify `type=bind`, the `source` path on our machine,
 and the `target` path _inside_ the container:
@@ -1455,17 +1484,18 @@ Ran 3 tests in 26.965s
 OK
 ----
 
-//RITA: I'd rather add exclamation marks than extend the word.
 AMAZING IT ACTUALLY WORKSSSSSSSS.
+//RITA: I'd rather add exclamation marks than extend the word.
 
 Ahem, that's definitely good enough for now!  Let's commit.
 
 
 [subs="specialcharacters,quotes"]
 ----
-$ *git add Dockerfile*
-$ *git commit -m"First cut of a Dockerfile"*
+$ *git add -A .*  # add Dockerfile, .dockerignore, .gitignore
+$ *git commit -am"First cut of a Dockerfile"*
 ----
+
 // DAVID: This is the second cut really?
 
 Phew.  Well, it took a bit of hacking about,
@@ -1478,9 +1508,8 @@ or running on port 8888 forever.
 In the next chapter, we'll make our hacky image more production-ready.
 
 But first, time for a well-earned tea break I think, and perhaps a
-https://en.wikipedia.org/wiki/Digestive_biscuit[chocolate biscuit].
+https://en.wikipedia.org/wiki/Digestive_biscuit#Chocolate_digestives[chocolate biscuit].
 
-// DAVID: That ain't no chocolate biscuit!
 
 .Test-Driving Server Configuration and Deployment
 *******************************************************************************