Merge branch 'main' into 20240411_chapter_11_jg_review

Author: hjwp

.github/workflows/tests.yml

@@ -33,6 +33,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - id: foo
-        uses: hjwp/github-actions@v5
+        uses: hjwp/github-actions@v6
         with:
           test_chapter: ${{ matrix.test_chapter }}

Makefile

@@ -47,7 +47,7 @@ build: $(HTML_PAGES) $(TMPDIR)
 
 
 .venv/bin:
-	which uv && uv venv .venv || python -m venv .venv
+	which uv && uv venv .venv || python3 -m venv .venv
 	which uv && uv pip install -e . || .venv/bin/pip install -e .
 
 .PHONY: install

acknowledgments.asciidoc

@@ -110,6 +110,8 @@ James Evans,
 Patrick Cantwell,
 Devin Schumacher,
 Nick Nielsen,
+Teemu Viikeri,
+Andrew Zipperer,
 and to anyone I've missed off this list,
 my sincere apologies, and thank you thank you once again.
 

chapter_04_philosophy_and_refactoring.asciidoc

@@ -716,7 +716,7 @@ NOTE: This is another distinction between FTs and unit tests;
     we use them as the primary tool for testing our UI,
     and the HTML that implements it.
 
-So, wanted an `<h1>`:
+So, we wanted an `<h1>`:
 
 [role="sourcecode"]
 .lists/templates/home.html (ch04l008)
@@ -916,7 +916,7 @@ but it should be enough to reassure ourselves that things are working.
 To get that functional test to green,
 we then enter into the lower-level unit tests cycle,
 where we put together all the moving parts required,
-add tests for all the edge cases.
+and add tests for all the edge cases.
 Any time we get to green & refactored at the unit tests level,
 we can pop back up to the FT level to guide us towards the
 next thing we need to work.

chapter_05_post_and_database.asciidoc

@@ -355,7 +355,7 @@ def home_page(request):
 OK that gets our unit tests passing, but it's not really what we want.footnote:[
 But we _did_ learn about `request.method` and `request.POST` right?
 I know it might seem that I'm overdoing it,
-but doing things in tiny little really does have a lot of advantages,
+but doing things in tiny little steps really does have a lot of advantages,
 and one of them is that you can really think about (or in this case, learn)
 one thing at a time.]
 
@@ -633,7 +633,7 @@ on applying DRY too quickly.
 
 
 Now we get to the `self.fail('Finish the test!')`.
-If get rid of that and finish writing our FT,
+If we get rid of that and finish writing our FT,
 to add the check for adding a second item to the table
 (copy and paste is our friend),
 we begin to see that our first cut solution really isn't going to, um, cut it:
@@ -964,7 +964,7 @@ django.db.utils.OperationalError: no such table: lists_item
 ----
 
 In Django, the ORM's job is to model and read and write from database tables,
-but there's a second system that's in charge,of actually _creating_
+but there's a second system that's in charge of actually _creating_
 the tables in the database called "migrations".
 Its job is to let you to add, remove, and modify tables and columns,
 based on changes you make to your _models.py_ files.

chapter_06_explicit_waits_1.asciidoc

@@ -445,7 +445,7 @@ to separate the timing and re-raising logic from the test assertions.
 But we'll wait until we need it in multiple places.
 
 NOTE: If you've used Selenium before, you may know that it has a few
-    https://www.selenium.dev/documentation/webdriver/waits/#explicit-wait[helper functions to do waits].
+    https://www.selenium.dev/documentation/webdriver/waits/#explicit-waits[helper functions to do waits].
     I'm not a big fan of them, though not for any objective reason really.
     Over the course of the book we'll build a couple of wait helper tools
     which I think will make for nice, readable code,

chapter_09_docker.asciidoc

@@ -1479,4 +1479,8 @@ Some typical pain points--networking, ports, static files, 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
+
 *******************************************************************************

chapter_10_production_readiness.asciidoc

@@ -41,14 +41,25 @@ so that people can access it using a regular URL.
 
 Perhaps more importantly, we shouldn't use the Django dev server for production;
 it's not designed for real-life workloads.
-Instead, we'll use the popular Gunicorn Python/WSGI server.
+Instead, we'll use the popular Gunicorn Python WSGI HTTP server.
+
+NOTE: Django's `runserver` is built and optimised for local development and debugging.
+  It's designed to handle one user at a time,
+  it handles automatic reloading upon saving of the source code,
+  but it isn't optimised for performance,
+  nor has it been hardened against security vulnerabilities.
 
 ((("DEBUG settings")))
 In addition, several options in _settings.py_ are currently unacceptable.
-`DEBUG=True`, is strongly recommended against for production,
+`DEBUG=True`, is strongly discouraged for production,
 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,
+  because the django debug page will display sensitive information like
+  the values of variables, and most of the settings in settings.py.
+
+
 Let's go through and see if we can fix things one by one.
 
 // SEBASTIAN: How about linking to Django's documentation
@@ -68,6 +79,47 @@ which I guess is what you'd want next if you already had a pony...
 We'll need to first install Gunicorn into our container,
 and then use it instead of `runserver`:
 
+//001
+
+[subs="specialcharacters,quotes"]
+----
+$ *pip install gunicorn*
+Collecting gunicorn
+[...]
+Successfully installed gunicorn-21.2.0
+----
+
+[[what-is-wsgi]]
+.What is WSGI?
+*******************************************************************************
+Gunicorn is a WSGI (usually pronounced as whizgee) HTTP server.
+Let's go through what this means:
+
+* An HTTP server handles incoming HTTP requests and sends back responses to the
+  clients.
+
+* WSGI, the Web Server Gateway Interface, is a set of rules defining how an HTTP
+  server (which can be Gunicorn itself, or Nginx, Apache, etc) and a Python
+  program should communicate.
+
+So, Gunicorn is an HTTP server that knows and uses the WSGI to "talk" to Python programs.
+And these Python programs are likewise expected to work in a specific way.
+You can check out a simple example https://gunicorn.org/[on Gunicorn's website] under "Installation".
+
+https://peps.python.org/pep-3333[If you are interested, you can read the entire
+specification here].
+
+// CSANAD:  I felt like some explanation regarding what Gunicorn and WSGI are,
+//          was missing.
+
+*******************************************************************************
+
+
+Gunicorn will need to know a path to a "WSGI server" (see <<what-is-wsgi>>),
+which is usually a function called `application`.
+Django provides one in 'superlists/wsgi.py'.
+Let's change the command our image runs:
+
 [role="sourcecode"]
 .Dockerfile (ch10l001)
 ====
@@ -83,6 +135,9 @@ WORKDIR /src
 CMD gunicorn --bind :8888 superlists.wsgi:application  <2>
 ----
 ====
+// CSANAD:  shouldn't we try it out before adding this to the Dockerfile?
+//          `cd src` and then
+// `gunicorn --bind :8888 superlists.wsgi:application`
 
 <1> Installation is a standard pip install.
 
@@ -172,6 +227,11 @@ MIDDLEWARE = [
 
 ----
 ====
+// CSANAD:  I would add a few thoughts on the significance of the order of
+//          middlewares.
+
+And if you take another manual look at your site after rebuilding the
+container, things should look much healthier.
 
 And then we need to add it to our pip installs in the Dockerfile:
 
@@ -290,7 +350,7 @@ Django, Gunicorn and Whitenoise:
 [subs="specialcharacters,quotes"]
 ----
 $ *pip freeze | grep -i django*
-Django==4.2.7
+Django==4.2.11
 
 $ *pip freeze | grep -i django >> requirements.txt*
 $ *pip freeze | grep -i gunicorn >> requirements.txt*
@@ -351,7 +411,7 @@ TIP: Itamar Turner-Traurig has a great guide to
 
 Now let's see how we use that requirements file in our Dockerfile:
 
-.Dockerfile (ch09l005)
+.Dockerfile (ch10l005)
 ====
 [source,dockerfile]
 ----
@@ -371,9 +431,9 @@ CMD python manage.py runserver
 ----
 ====
 
-<3> We COPY our requirements file in, just like the src folder.
+<1> We COPY our requirements file in, just like the src folder.
 
-<4> Now instead of just installing Django, we install all our dependencies
+<2> Now instead of just installing Django, we install all our dependencies
   by pointing pip at the _requirements.txt_ using the `-r` flag.
   Notice the `-r`.
 
@@ -437,7 +497,8 @@ Environment variables also have the advantage of working for non-Django stuff to
 ==== Setting DEBUG=True and SECRET_KEY
 
 //RITA: What do you mean by "this"? Please add a word or two for context.
-There's lots of ways you might do this.
+There are lots of ways you might do this.
+
 Here's what I propose; it may seem a little fiddly,
 but I'll provide a little justification for each choice.
 Let them be an inspiration (but not a template) for your own choices!
@@ -459,6 +520,10 @@ else:
     SECRET_KEY = "insecure-key-for-dev"
 ----
 ====
+// CSANAD: I think variable names like "something_false" are confusing, since
+//         we need to set something to true so that they mean false.
+// How about `DJANGO_ENV_PRODUCTION` or something similar?
+// TODO yes i like this
 
 <1> We say we'll use an environment variable called `DJANGO_DEBUG_FALSE`
     to switch debug mode off, and in effect require production settings
@@ -479,6 +544,14 @@ against accidentally forgetting to set one.
 TIP: Better to fail hard than allow a typo in an environment variable name to
     leave you running with insecure settings.
 
+// CSANAD: I think it would worth pointing out the development environment
+//         does not use Docker, launching the dev server should be done from
+// the reader's host system. I think this isn't immediately obvious, e.g. I
+// thought all along that from now on we would only run the server from Docker.
+// If we end up making a TIP or similar about it, I think we should also mention
+// in a development environment relying on containerization, programmers usually
+// mount the whole /src minimizing the time-consuming rebuilding of their images.
+
 ==== Setting environment variables inside the Dockerfile
 
 Now let's set that environment variable in our Dockerfile using the `ENV` directive:
@@ -555,6 +628,9 @@ It's not quite working yet!  Let's take a look manually: <<django-400-error>>.
 .An ugly 400 error
 image::images/twp2_1002.png["An unfriendly page showing 400 Bad Request"]
 
+// DAVID: noticed in passing that the screenshots in this chapter are from the hosted version
+// which isn't covered until next chapter.
+
 We've set our two environment variables but doing so seems to have broken things.
 But once again, by running our FTs frequently,
 we're able to identify the problem early,
@@ -627,6 +703,10 @@ $ *docker build -t superlists . && docker run \
 An FT run (or just looking at the site) reveals that we've had a regression
 in our static files:
 
+// CSANAD: worth mentioning there was another clue. in the logs, once Gunicorn
+//         starts running you can see:
+// `UserWarning: No directory at: /src/static/`
+
 [role="small-code"]
 [subs="specialcharacters,macros"]
 ----
@@ -658,6 +738,7 @@ ENV DJANGO_DEBUG_FALSE=1
 CMD gunicorn --bind :8888 superlists.wsgi:application
 ----
 ====
+// CSANAD: I think it would be important to use a non-privileged user in Docker
 
 // DAVID: It would be nice to explain the difference between RUN and CMD.
 
@@ -698,6 +779,12 @@ $ *git status*
 $ *git commit -am "Add collectstatic to dockerfile, and new location to gitignore"*
 ----
 
+// CSANAD: now would be a good time to check our changes and notice git marked
+//         src/static as unstaged, so we should update .gitignore accordingly:
+// from `static` to `src/static`.
+// Or we could add this step to Chapter 09 at "Move all our code into a src
+// folder"
+
 
 === Switching to a nonroot user
 
@@ -715,7 +802,6 @@ USER nonroot
 ----
 
 
-
 === Configuring logging
 
 One last thing we'll want to do is make sure that we can get logs out of our server.
@@ -777,7 +863,7 @@ but it's more of shock to see that they are no longer appearing in the terminal
 If you're like me you might find yourself wondering if we really _did_ see them earlier
 and starting to doubt your own sanity.
 But the explanation is that Django's
-https://docs.djangoproject.com/en/5.0/ref/logging/#default-logging-configuration[default logging configuration]
+https://docs.djangoproject.com/en/4.2/ref/logging/#default-logging-configuration[default logging configuration]
 changes when DEBUG is turned off:
 
 This means we need to interact with the standard library's `logging` module,
@@ -790,7 +876,7 @@ but sometimes you just wanna say "just print stuff to stdout pls",
 and you wish that configuring the simplest thing was a little easier.].
 
 Here's pretty much the simplest possible logging config
-which just prints everything to the console (ie standard out).
+which just prints everything to the console (i.e. standard out).
 
 
 [role="sourcecode"]
@@ -832,7 +918,7 @@ django.db.utils.OperationalError: no such table: lists_list
 
 Re-create the database with `./src/manage.py migrate` and we'll be back to a working state.
 
-Don't forget to commit our changes to _settings.py_,
+Don't forget to commit our changes to _settings.py_ and _Dockerfile_,
 and I think we can call it job done!
 We've at least touched on many or most of the things you might need to think about
 when considering production-readiness,