better recap in 9, tweak warnings in 9+10, add some footnotes

hjwp · hjwp · commit 7fc56ea7a011 · 2025-04-23T23:11:04.000+01:00
diff --git a/chapter_09_docker.asciidoc b/chapter_09_docker.asciidoc
@@ -3,11 +3,18 @@
 
 .A Note for Early Release Readers
 ****
-With Early Release ebooks, you get books in their earliest form—the author's raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.
-
-This will be the 9th chapter of the final book. The GitHub repo is available at https://github.com/hjwp/book-example/tree/chapter_09_docker.
-
-If you have comments about how we might improve the content and/or examples in this book, or if you notice missing material within this chapter, please reach out to the author at obeythetestinggoat@gmail.com.
+With Early Release ebooks, you get books in their earliest form--the
+author's raw and unedited content as they write--so
+you can take advantage of these technologies
+long before the official release of these titles.
+
+This will be the 9th chapter of the final book.
+The GitHub repo is available at https://github.com/hjwp/book-example/tree/chapter_09_docker.
+
+If you have comments about how we might improve the content
+and/or examples in this book,
+or if you notice missing material within this chapter,
+please reach out to the author at obeythetestinggoat@gmail.com.
 ****
 
 [quote, Malvina Reynolds]']
@@ -28,6 +35,17 @@ and get those tests passing our code running inside Docker.
 * We'll start flushing out a few issues around networking and the database.
 
 
+.Warning, Fresh Content
+****
+Just to reinforce on the ER note above,
+the content for this chapter is all brand new for the third edition,
+so I'm particularly keen on feedback and suggestions for it.
+
+So please hit me up at obeythetestinggoat@gmail.com, or via
+https://github.com/hjwp/Book-TDD-Web-Dev-Python/issues[GitHub Issues]
+and Pull Requests.
+****
+
 === Docker, Containers and Virtualization
 
 Docker is a commercial product that wraps several free
@@ -1351,7 +1369,11 @@ $ *echo src/db.sqlite3 >> .dockerignore*
 
 Now we 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,
+where we specify `type=bind`, the `source` path on our machine,footnote:[
+If you're wondering about the `$PWD` in the listing,
+it's a special environment variable that represents the current directory.
+The initials echo the `pwd` command, which stands for "print working directory".
+Docker requires mount paths to be absolute paths.]
 and the `target` path _inside_ the container:
 
 [subs="specialcharacters,quotes"]
@@ -1369,10 +1391,6 @@ TIP: You're likely to come across the old syntax for mounts, which was `-v`.
     This avoids a lot of pain, ask me how I know this.
 
 
-NOTE: If you see an error from Docker saying "mount path must be absolute",
-    replace the source path with `source="$PWD/src/db.sqlite3"`
-
-
 [role="small-code"]
 [subs="specialcharacters,macros"]
 ----
@@ -1409,26 +1427,34 @@ But first, time for a well-earned tea break I think, and perhaps a
 https://en.wikipedia.org/wiki/Digestive_biscuit#Chocolate_digestives[chocolate biscuit].
 
 
-.Test-Driving Server Configuration and Deployment
+.Docker Recap
 *******************************************************************************
 
-Tests and small steps take some of the uncertainty out of deployment::
+Docker lets us reproduce a server environment on our own machine::
     For developers, ops and infra work is always "fun",
     by which I mean a process full of fear, uncertainty and surprises.
-    My aim during this chapter was to show that a step-by-step approach
-    helps to minimise risk, especially when allied to a functional test suite
-    that can help us to catch errors early.
-
-Some typical pain points--networking, ports, static files, and the database::
-    Moving from the local django development server to a container
-    is a chance to rehearse the fiddliness of configuring networking
-    in a deployed environment.
-    It's also a chance to think about persistence and the database,
-    and some configuration issues like static files.
-
-
-// TODO: add debugging tips docker ps, docker inspect, docker logs.
-// also brief description of network debugging:  try curl outside, try curl inside, restart pc / docker /colima
-// also maybe the lsof command to see who's using what port
+    And painfully slow too.
+    Docker helps to minimise this pain,
+    by giving a mini-server on our own machine,
+    that we can trying things out with and get feedback quickly,
+    as well as enabling working in small steps.
+
+`docker build && docker run`::
+    We've learned the core tools for working with Docker.
+    The Dockerfile specifies our image, `docker build` builds it,
+    and `docker run` runs it.
+    `build && run` together give us a "start again from scratch" cycle.
+
+Debugging network issues::
+    We've seen how to use `curl` both outside and inside the container
+    with `docker exec`.
+    We've also seen the `-p` argument to bind ports inside and outside,
+    and the idea of needing to bind to `0.0.0.0`.
+
+Mounting files::
+    We've also had a brief intro to mounting files from outside
+    the container, into the inside.
+    It's an insight into the difference between the "stateless"
+    system image, and the stateful world outside of Docker.
 
 *******************************************************************************
diff --git a/chapter_10_production_readiness.asciidoc b/chapter_10_production_readiness.asciidoc
@@ -3,11 +3,18 @@
 
 .A Note for Early Release Readers
 ****
-With Early Release ebooks, you get books in their earliest form—the author's raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.
-
-This will be the 10th chapter of the final book. The GitHub repo is available at https://github.com/hjwp/book-example.
-
-If you have comments about how we might improve the content and/or examples in this book, or if you notice missing material within this chapter, please reach out to the author at obeythetestinggoat@gmail.com.
+With Early Release ebooks, you get books in their earliest form--the
+author's raw and unedited content as they write--so
+you can take advantage of these technologies
+long before the official release of these titles.
+
+This will be the 10th chapter of the final book.
+The GitHub repo is available at https://github.com/hjwp/book-example/tree/chapter_10_production_readiness
+
+If you have comments about how we might improve the content
+and/or examples in this book,
+or if you notice missing material within this chapter,
+please reach out to the author at obeythetestinggoat@gmail.com.
 ****
 
 Our container is working fine but it's not production-ready.
@@ -20,14 +27,12 @@ trying to move from working state to working state,
 and using the FTs to detect any regressions.
 
 
-.Warning, chapter under construction
+.Warning, Fresh Content
 ****
-As part of my work on the third edition of the book,
-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.
+Just to reinforce on the ER note above,
+the content for this chapter is all brand new for the third edition,
+so I'm particularly keen on feedback and suggestions for it.
 
-But as always I really, really need feedback.
 So please hit me up at obeythetestinggoat@gmail.com, or via
 https://github.com/hjwp/Book-TDD-Web-Dev-Python/issues[GitHub Issues]
 and Pull Requests.
@@ -55,7 +60,7 @@ In addition, several options in _settings.py_ are currently unacceptable.
 we'll want to set a unique `SECRET_KEY`,
 and, as we'll see, other things will come up.
 
-NOTE: DEBUG=True is considered a security risk,
+WARNING: DEBUG=True is considered a security risk,
   because the django debug page will display sensitive information like
   the values of variables, and most of the settings in settings.py.
 
@@ -66,6 +71,20 @@ Let's go through and see if we can fix things one by one.
 //      https://docs.djangoproject.com/en/5.0/howto/deployment/
 //      somewhere later in the chapter for curious readers?
 
+
+////
+HARRY
+manage.py check --deploy gives 
+WARNINGS:
+?: (security.W004) You have not set a value for the SECURE_HSTS_SECONDS setting. If your entire site is served only over SSL, you may want to consider setting a value and enabling HTTP Strict Transport Security. Be sure to read the documentation first; enabling HSTS carelessly can cause serious, irreversible problems.
+?: (security.W008) Your SECURE_SSL_REDIRECT setting is not set to True. Unless your site should be available over both SSL and non-SSL connections, you may want to either set this setting True or configure a load balancer or reverse-proxy server to redirect all connections to HTTPS.
+?: (security.W009) Your SECRET_KEY has less than 50 characters, less than 5 unique characters, or it's prefixed with 'django-insecure-' indicating that it was generated automatically by Django. Please generate a long and random value, otherwise many of Django's security-critical features will be vulnerable to attack.
+?: (security.W012) SESSION_COOKIE_SECURE is not set to True. Using a secure-only session cookie makes it more difficult for network traffic sniffers to hijack user sessions.
+?: (security.W016) You have 'django.middleware.csrf.CsrfViewMiddleware' in your MIDDLEWARE, but you have not set CSRF_COOKIE_SECURE to True. Using a secure-only CSRF cookie makes it more difficult for network traffic sniffers to steal the CSRF token.
+?: (security.W018) You should not have DEBUG set to True in deployment.
+?: (security.W020) ALLOWED_HOSTS must not be empty in deployment.
+////
+
 === Switching to Gunicorn
 
 ((("production-ready deployment", "using Gunicorn", secondary-sortas="Gunicorn")))
@@ -137,12 +156,11 @@ $ *docker build -t superlists . && docker run \
   -it superlists*
 ----
 
-// DAVID: Incidentally I got the following error:
-// Bind for 0.0.0.0:8888 failed: port is already allocated.
-// Turned out the previous container was still running,
-// I just used the docker kill process you taught me about earlier.
-// Not sure if it's worth including that here, possibly clutter?
-
+TIP: If you see an error saying
+  `Bind for 0.0.0.0:8888 failed: port is already allocated.`,
+  it'll be because you still have a container running from the previous chapter.
+  Do you remember how to use `docker ps`, and `docker stop`?
+  Otherwise, skip back to <<how-to-stop-a-docker-container>>.
 
 ==== The FTs catch a problem with static files
 
@@ -197,7 +215,10 @@ First we install Whitenoise into our local environment:
 *pip install whitenoise*
 ----
 
-Then we tell Django to enable it, in _settings.py_:
+Then we tell Django to enable it, in _settings.py_footnote:[
+Find out more about Django Middleware
+in https://docs.djangoproject.com/en/5.1/topics/http/middleware/[the docs].
+]:
 
 [role="sourcecode"]
 .src/superlists/settings.py (ch10l002)
@@ -212,8 +233,6 @@ MIDDLEWARE = [
 
 ----
 ====
-// CSANAD:  I would add a few thoughts on the significance of the order of
-//          middlewares.
 
 And then we need to add it to our pip installs in the Dockerfile:
 
