chore: pin at debian 12

.devcontainer/devcontainer.json

@@ -3,6 +3,7 @@
   "dockerComposeFile": ["../compose.yml"],
   "service": "dev",
   "runServices": ["dev", "docs"],
+  "forwardPorts": ["docs:8001"],
   "workspaceFolder": "/calitp/app",
   "postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"],
   // Set *default* container specific settings.json values on container create.

README.md

@@ -6,7 +6,7 @@ Read the full documentation online: <https://docs.calitp.org/docker-python-web>
 
 ## Features
 
-- Base image `python:3.12`
+- Base image `python:3.12-bookworm`
 - Image configured with non-`root` user (`calitp` by default)
 - `nginx` configured as a reverse proxy listening on container port `8000`
 - `gunicorn` configured as a WSGI application server, communicates with `nginx` over Unix socket
@@ -51,6 +51,16 @@ docker compose build app
 
 Then, with the [Remote - Containers](https://code.visualstudio.com/docs/remote/containers) extension enabled, open the folder containing this repository inside Visual Studio Code.
 
+The image you just built can be accessed from other (local) codebases via:
+
+```dockerfile
+FROM docker-python-web:app
+```
+
+## Docs
+
+While the devcontainer is running, documentation can be found at [http://localhost:8001/docker-python-web](http://localhost:8001/docker-python-web)
+
 ## License
 
 [Apache 2.0](LICENSE)

appcontainer/Dockerfile

@@ -6,7 +6,11 @@ ARG PYTHON_VERSION=3.12 \
     USER_UID=1000 \
     USER_GID=1000
 
-FROM python:3.12
+# we can start using debian 13 as soon as an ubuntu 26.04 hosted github actions runner image is available
+# https://github.com/actions/runner-images
+# https://launchpad.net/ubuntu/resolute/+package/gettext
+# https://packages.debian.org/trixie/gettext
+FROM python:3.12-bookworm
 
 # renew top-level args in this stage
 ARG PYTHON_VERSION \

compose.yml

@@ -26,7 +26,7 @@ services:
   docs:
     image: docker-python-web:dev
     entrypoint: mkdocs
-    command: serve --dev-addr "0.0.0.0:8001"
+    command: serve --livereload --dev-addr "0.0.0.0:8001"
     ports:
       - "8001"
     volumes:

docs/README.md

@@ -8,7 +8,7 @@ This is the documentation site for [`cal-itp/docker-python-web`](https://github.
 
 ## Features
 
-- Base image `python:3.12`
+- Base image `python:3.12-bookworm`
 - Image configured with non-`root` user (`calitp` by default)
 - `nginx` configured as a reverse proxy listening on container port `8000`
 - `gunicorn` configured as a WSGI application server, communicates with `nginx` over Unix socket
@@ -53,3 +53,9 @@ Development for this repo is done within a Visual Studio Code [devcontainer](htt
     ```
 
 Then, with the [Remote - Containers](https://code.visualstudio.com/docs/remote/containers) extension enabled, open the folder containing this repository inside Visual Studio Code.
+
+The image you just built can be accessed from other (local) codebases via:
+
+```dockerfile
+FROM docker-python-web:app
+```

docs/guides/testing-changes.md

@@ -0,0 +1,71 @@
+# Testing changes
+
+Each time we update the underlying version of Python or the base OS the steps below are a good way to verify compatibility.
+
+- Make sure the change is compatible with the python dependencies of dependent projects
+- In your `docker-python-web` repository, rebuild the local image:
+
+  ```bash
+  docker compose build app --no-cache
+  ```
+
+## Test [Benefits](https://docs.calitp.org/benefits/) with the updated local base image
+
+In your `benefits` repository:
+
+1. In the benefits Dockerfile:
+
+   ```bash
+   ghcr.io/cal-itp/docker-python-web:main
+   # becomes
+   docker-python-web:app
+   ```
+
+1. Rebuild Benefits image
+
+   ```bash
+   docker compose build client --no-cache
+   ```
+
+1. Open Benefits devcontainer with "Rebuild Without Cache and Reopen in Container"
+1. Run app locally and go through a few full flows
+1. Verify that unit tests pass
+
+## Test [eligibility-server](https://docs.calitp.org/eligibility-server/) with the updated local base image
+
+In your `eligibility-server` repository
+
+1. In the eligibility-server Dockerfile:
+
+   ```bash
+     ghcr.io/cal-itp/docker-python-web:main
+     # becomes
+     docker-python-web:app
+   ```
+
+1. Rebuild eligibility-server image
+
+   ```bash
+     docker compose build server --no-cache
+   ```
+
+1. Open eligibility-server devcontainer with "Rebuild Without Cache and Reopen in Container"
+1. Verify that unit tests pass
+
+And confirm the update works in benefits:
+
+1. Use the local `eligibility_server:latest` image as the Benefits compose.yml `server` service
+1. Rebuild the benefits container
+1. Run app locally and test the Courtesy Card flow
+
+## Follow-up
+
+After a Python upgrade is complete, we follow-up in dependent projects above by updating:
+
+- [`.github/workflows/.python-version`](https://github.com/cal-itp/benefits/blob/be4e7b37acfbd40dabd08ecf3dd2b5b227d8fd3d/.github/workflows/.python-version)
+- `tool.black.target-version` in [`pyproject.toml`](https://github.com/cal-itp/benefits/blob/be4e7b37acfbd40dabd08ecf3dd2b5b227d8fd3d/pyproject.toml#L61)
+
+We also update related projects that use an official image for the sake of parity.
+
+- [littlepay](https://github.com/cal-itp/littlepay/pull/75)
+- [eligibility-api](https://github.com/cal-itp/eligibility-api/pull/107)

mkdocs.yml

@@ -6,6 +6,7 @@ site_url: https://docs.calitp.org/docker-python-web
 theme:
   name: material
   features:
+    - content.code.copy
     - navigation.expand
     - navigation.tabs
   palette: