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/README.md b/README.md index 851b8e5..4af13c6 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 @@ -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) diff --git a/appcontainer/Dockerfile b/appcontainer/Dockerfile index 5732a9b..e289187 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 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 \ 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/README.md b/docs/README.md index 5f47a68..1753915 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 @@ -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 +``` diff --git a/docs/guides/testing-changes.md b/docs/guides/testing-changes.md new file mode 100644 index 0000000..ab4e6b1 --- /dev/null +++ b/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) 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: