From 8c30092cc7e66ac45714b2a4564279abac37d364 Mon Sep 17 00:00:00 2001 From: John Gravois Date: Wed, 11 Mar 2026 01:01:20 +0000 Subject: [PATCH 1/6] chore: pin at debian 12 --- README.md | 2 +- appcontainer/Dockerfile | 6 +++++- docs/README.md | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 851b8e5..9219abf 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Read the full documentation online: ## 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 diff --git a/appcontainer/Dockerfile b/appcontainer/Dockerfile index 5732a9b..ed8e8f0 100644 --- a/appcontainer/Dockerfile +++ b/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 25.04+ hosted github actions runner image is available +# https://github.com/actions/runner-images +# https://launchpad.net/ubuntu/plucky/+package/gettext +# https://packages.debian.org/trixie/gettext +FROM python:3.12-bookworm # renew top-level args in this stage ARG PYTHON_VERSION \ diff --git a/docs/README.md b/docs/README.md index 5f47a68..d998f23 100644 --- a/docs/README.md +++ b/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 From d6f61d0ca2f64cc3f1fada59b41e6faa3a6bc33c Mon Sep 17 00:00:00 2001 From: John Gravois Date: Wed, 11 Mar 2026 03:41:28 +0000 Subject: [PATCH 2/6] docs: add snippet referencing locally built image --- README.md | 6 ++++++ docs/README.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/README.md b/README.md index 9219abf..fefdbe4 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,12 @@ 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 +``` + ## License [Apache 2.0](LICENSE) diff --git a/docs/README.md b/docs/README.md index d998f23..8ef6587 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,4 +52,10 @@ Development for this repo is done within a Visual Studio Code [devcontainer](htt docker compose build app ``` +The image you just built can be accessed from other (local) codebases via: + +```dockerfile +FROM docker-python-web: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. From f2b4f0b8bfbfd8cec0f21854aab5e2c9eff81546 Mon Sep 17 00:00:00 2001 From: John Gravois Date: Thu, 12 Mar 2026 00:15:31 +0000 Subject: [PATCH 3/6] chore: add guide for testing changes --- docs/README.md | 4 ++-- docs/guides/testing-changes.md | 35 ++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 docs/guides/testing-changes.md diff --git a/docs/README.md b/docs/README.md index 8ef6587..1753915 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,10 +52,10 @@ Development for this repo is done within a Visual Studio Code [devcontainer](htt 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 ``` - -Then, with the [Remote - Containers](https://code.visualstudio.com/docs/remote/containers) extension enabled, open the folder containing this repository inside Visual Studio Code. diff --git a/docs/guides/testing-changes.md b/docs/guides/testing-changes.md new file mode 100644 index 0000000..dc0d4c2 --- /dev/null +++ b/docs/guides/testing-changes.md @@ -0,0 +1,35 @@ +# 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 +- Rebuild the local image - `docker compose build app --no-cache` + +## Test [Benefits](https://docs.calitp.org/benefits/) with the updated local base image + +1. Update Benefits Dockerfile to use `docker-python-web:app` +1. Rebuild Benefits image - `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 + +1. Update eligibility-server Dockerfile to use `docker-python-web:app` +1. Rebuild eligibility-server image - `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 +1. Point Benefits compose.yml at local `eligibility_server:latest` image +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) From a6815ba28eb98b13c85b782bf82eea13c3661ece Mon Sep 17 00:00:00 2001 From: John Gravois Date: Thu, 12 Mar 2026 20:41:19 +0000 Subject: [PATCH 4/6] chore: wire up port forwarding, address code review --- .devcontainer/devcontainer.json | 1 + appcontainer/Dockerfile | 4 +-- docs/guides/testing-changes.md | 48 ++++++++++++++++++++++++++++----- mkdocs.yml | 1 + 4 files changed, 46 insertions(+), 8 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index bafd587..833597e 100644 --- a/.devcontainer/devcontainer.json +++ b/.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. diff --git a/appcontainer/Dockerfile b/appcontainer/Dockerfile index ed8e8f0..e289187 100644 --- a/appcontainer/Dockerfile +++ b/appcontainer/Dockerfile @@ -6,9 +6,9 @@ ARG PYTHON_VERSION=3.12 \ USER_UID=1000 \ USER_GID=1000 -# we can start using debian 13+ as soon as an ubuntu 25.04+ hosted github actions runner image is available +# 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/plucky/+package/gettext +# https://launchpad.net/ubuntu/resolute/+package/gettext # https://packages.debian.org/trixie/gettext FROM python:3.12-bookworm diff --git a/docs/guides/testing-changes.md b/docs/guides/testing-changes.md index dc0d4c2..ab4e6b1 100644 --- a/docs/guides/testing-changes.md +++ b/docs/guides/testing-changes.md @@ -3,23 +3,59 @@ 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 -- Rebuild the local image - `docker compose build app --no-cache` +- 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 -1. Update Benefits Dockerfile to use `docker-python-web:app` -1. Rebuild Benefits image - `docker compose build client --no-cache` +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 -1. Update eligibility-server Dockerfile to use `docker-python-web:app` -1. Rebuild eligibility-server image - `docker compose build server --no-cache` +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 -1. Point Benefits compose.yml at local `eligibility_server:latest` image + +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 diff --git a/mkdocs.yml b/mkdocs.yml index da2a833..0d8d711 100644 --- a/mkdocs.yml +++ b/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: From b6dbdd534d37614e9b02d139dada4d1e5b601803 Mon Sep 17 00:00:00 2001 From: John Gravois Date: Thu, 12 Mar 2026 20:51:15 +0000 Subject: [PATCH 5/6] chore: fix mkdocs watching and mention port in README --- README.md | 4 ++++ docs/requirements.txt | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/README.md b/README.md index fefdbe4..4af13c6 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,10 @@ The image you just built can be accessed from other (local) codebases via: 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) diff --git a/docs/requirements.txt b/docs/requirements.txt index c35ca8d..54203b4 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,9 @@ +# Temporary local pin to work around bug in click>=8.2.2 that breaks watching. +# See: https://github.com/squidfunk/mkdocs-material/issues/8478 +# https://github.com/mkdocs/mkdocs/issues/4032 +# https://github.com/pallets/click/issues/3084 +# Remove when a fixed version of Click has been released +click==8.2.1 mkdocs mkdocs-awesome-pages-plugin mkdocs-macros-plugin From 52417108df2362b688dbfcb46fc12f3a8acfdfd6 Mon Sep 17 00:00:00 2001 From: John Gravois Date: Fri, 13 Mar 2026 20:49:47 +0000 Subject: [PATCH 6/6] chore: add --livereload mkdocs flag instead of pinning click --- compose.yml | 2 +- docs/requirements.txt | 6 ------ 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/compose.yml b/compose.yml index 3d310ae..a1a3ab7 100644 --- a/compose.yml +++ b/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: diff --git a/docs/requirements.txt b/docs/requirements.txt index 54203b4..c35ca8d 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,9 +1,3 @@ -# Temporary local pin to work around bug in click>=8.2.2 that breaks watching. -# See: https://github.com/squidfunk/mkdocs-material/issues/8478 -# https://github.com/mkdocs/mkdocs/issues/4032 -# https://github.com/pallets/click/issues/3084 -# Remove when a fixed version of Click has been released -click==8.2.1 mkdocs mkdocs-awesome-pages-plugin mkdocs-macros-plugin