v2.5.5

.devenv-version

@@ -1 +1 @@
-0.2.0
+0.2.11

.dockerignore

@@ -12,7 +12,8 @@
 *~
 .*cache
 .DS_Store
-.claude
+.claude/settings.local.json
+.claude/worktrees
 .coverage*
 .docker-token
 .env*

.github/actions/devenv-lint-tools/action.yml

@@ -0,0 +1,27 @@
+# Managed by devenv (copy/ci). Edit it there, not in a child repo.
+name: devenv lint tools
+description: >-
+  Install the lint tools devenv's bin/ scripts run with Homebrew and put them
+  on PATH for later steps. The latest of each, as on the dev machines. Works
+  on ubuntu runners, where Homebrew is installed but not on PATH, and on macOS.
+inputs:
+  tools:
+    description: Space-separated Homebrew formulae to install.
+    default: shellcheck shellharden shfmt hadolint dockerfmt actionlint
+runs:
+  using: composite
+  steps:
+    - name: Install lint tools with Homebrew
+      shell: bash
+      env:
+        TOOLS: ${{ inputs.tools }}
+        HOMEBREW_NO_AUTO_UPDATE: "1"
+        HOMEBREW_NO_INSTALL_CLEANUP: "1"
+        HOMEBREW_NO_ANALYTICS: "1"
+      run: |
+        if [[ -x /home/linuxbrew/.linuxbrew/bin/brew ]]; then
+          eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+        fi
+        read -ra formulae <<<"$TOOLS"
+        brew install "${formulae[@]}"
+        echo "$(brew --prefix)/bin" >>"$GITHUB_PATH"

.github/workflows/devenv-check.yml

@@ -2,9 +2,10 @@
 #
 # Gate, one CI image build, a fail-fast lint/test/build matrix that pulls that
 # image, and the required-check aggregator. With container: false the matrix
-# runs natively on inputs.runner instead (for macOS-only projects) and no
-# image is built. Call it from a job in ci.yml; later jobs read its outputs
-# instead of repeating any trigger logic:
+# runs natively on inputs.runner instead (for macOS-only projects), no image
+# is built and the lint combo installs the lint tools with brew. Call it from
+# a job in ci.yml; later jobs read its outputs instead of repeating any
+# trigger logic:
 #
 #   ci:
 #     uses: ./.github/workflows/devenv-check.yml
@@ -36,23 +37,24 @@ on:
         description: >-
           true runs every combo in the CI image built from the Dockerfile.
           false runs it natively on the runner after setup-uv, setup-bun and
-          make install, for projects that cannot run in a Linux container.
+          make install, for projects that cannot run in a Linux container; a
+          combo that runs lint installs the lint tools with brew first.
         type: boolean
         default: true
       runner:
         description: >-
           Runner for the check matrix, e.g. macos-latest with container false.
-          The gate, image and result jobs stay on ubuntu-24.04.
+          The gate, image and result jobs stay on ubuntu-latest.
         type: string
-        default: ubuntu-24.04
+        default: ubuntu-latest
       release-preflight:
         description: >-
           Run bin/release-tag.sh preflight in the gate on main pushes and pull
           requests into main.
         type: boolean
         default: true
       retention-days:
-        description: Days to keep python-dist and the ci-passed marker.
+        description: Days to keep python-dist, the ci-passed marker and coverage.
         type: number
         default: 7
     outputs:
@@ -93,7 +95,7 @@ jobs:
   # ---------------------------------------------------------------------------
   gate:
     name: Gate
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     if: >-
       (github.event_name == 'push' && github.ref_name == 'main')
@@ -179,7 +181,7 @@ jobs:
     name: CI Image
     needs: gate
     if: inputs.container && needs.gate.outputs.dist_found != 'true'
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     # The slowest job: a cold build without the registry cache.
     timeout-minutes: 45
     permissions:
@@ -235,7 +237,7 @@ jobs:
   prune:
     name: Prune CI Images
     needs: image
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     continue-on-error: true
     permissions:
@@ -296,6 +298,12 @@ jobs:
         if: ${{ !inputs.container }}
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
 
+      # Only the combo that lints pays for the install. In container mode the
+      # CI stage of the project's Dockerfile has the tools.
+      - name: Install lint tools
+        if: ${{ !inputs.container && contains(matrix.make, 'lint') }}
+        uses: ./.github/actions/devenv-lint-tools
+
       - name: Install
         if: ${{ !inputs.container }}
         run: |
@@ -326,6 +334,17 @@ jobs:
           name: test-results-${{ strategy.job-index }}
           path: "**/test-results/pytest/*.xml"
 
+      # pytest-cov's HTML report. A project whose tests write none, such as
+      # one with pytest addopts of its own, has nothing to upload.
+      - name: Upload Coverage
+        if: matrix.junit && !cancelled() && steps.work.outcome != 'skipped'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: coverage-${{ strategy.job-index }}
+          path: "**/test-results/coverage/"
+          retention-days: ${{ inputs.retention-days }}
+          if-no-files-found: ignore
+
       - name: Publish Test Report
         if: matrix.junit && !cancelled() && steps.upload-tests.outcome == 'success'
         uses: mikepenz/action-junit-report@b7b80d7ac5b1da46d6aaff9fb57ad50d8453bcb3 # v6.6.0
@@ -354,7 +373,7 @@ jobs:
     # always(), not !cancelled(): a skipped required check counts as passing,
     # so a cancelled run must still reach this job and go red.
     if: ${{ always() && needs.gate.result != 'skipped' }}
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions: {}
     steps:

.github/workflows/devenv-release.yml

@@ -20,7 +20,7 @@ env:
 jobs:
   release:
     name: Tag, Release & Merge to Develop
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-latest
     timeout-minutes: 10
     permissions:
       contents: write # tag push, develop push, gh release create

.gitignore

@@ -16,6 +16,8 @@
 .DS_Store
 .Python
 .claude
+.claude/settings.local.json
+.claude/worktrees/
 .coverage*
 .coverage.*
 .dmypy.json
@@ -48,7 +50,6 @@ MANIFEST
 TODO.md
 __pycache__/
 __pypackages__/
-__snapshots__
 build
 celerybeat-schedule
 celerybeat.pid

.prettierignore

@@ -1,7 +1,8 @@
 *.sh
 *Dockerfile
 .*cache
-.claude
+.claude/settings.local.json
+.claude/worktrees/
 .git
 .venv*
 __pycache__

.readthedocs.yaml

@@ -1,5 +1,5 @@
 build:
-  os: ubuntu-24.04
+  os: ubuntu-lts-latest
   tools:
     python: "3"
 mkdocs:

Dockerfile

@@ -13,7 +13,7 @@
 ###############################################################################
 
 # ---- Stage 1: builder (build tools + Node for compilation) -----------------
-FROM nikolaik/python-nodejs:python3.14-nodejs26 AS builder-base
+FROM nikolaik/python-nodejs:python3.15-nodejs26 AS builder-base
 # nodejs25 blocked on bug https://github.com/nodejs/node/issues/60303
 
 COPY debian.sources /etc/apt/sources.list.d/
@@ -40,17 +40,18 @@ RUN pip3 install --no-cache --upgrade pip
 FROM oven/bun:latest AS bun-source
 FROM builder-base AS codex-ci
 
-# hadolint ignore=DL3008
-RUN apt-get clean \
-    && apt-get update \
-    && apt-get install --no-install-recommends -y \
-        shellcheck \
-    && apt-get clean \
-    && rm -rf /var/lib/apt/lists/*
-
 COPY --from=bun-source /usr/local/bin/bun /usr/local/bin/bun
 COPY --from=bun-source /usr/local/bin/bunx /usr/local/bin/bunx
 
+# Lint tools devenv's bin/ scripts run, unpinned on purpose.
+COPY --from=koalaman/shellcheck:stable /bin/shellcheck /usr/local/bin/
+COPY --from=mvdan/shfmt:latest /bin/shfmt /usr/local/bin/
+COPY --from=hadolint/hadolint:latest /bin/hadolint /usr/local/bin/
+COPY --from=rhysd/actionlint:latest /usr/local/bin/actionlint /usr/local/bin/
+COPY --from=ghcr.io/reteps/dockerfmt:latest /ko-app/dockerfmt /usr/local/bin/
+ADD https://github.com/anordal/shellharden/releases/latest/download/shellharden-x86_64-unknown-linux-musl.tar.gz /tmp/shellharden.tar.gz
+RUN tar -xzf /tmp/shellharden.tar.gz -C /usr/local/bin shellharden && rm /tmp/shellharden.tar.gz
+
 WORKDIR /app
 
 # Python deps (cacheable when lockfiles unchanged)
@@ -86,7 +87,7 @@ COPY pyproject.toml uv.lock ./
 COPY dist/${CODEX_WHEEL} ./
 # Pin the runtime closure to uv.lock; install the wheel itself without deps.
 RUN uv export --frozen --no-default-groups --no-emit-project -o requirements.txt \
-    && uv venv --python /usr/local/bin/python3.14 /opt/codex \
+    && uv venv --python /usr/local/bin/python3.15 /opt/codex \
     && PYMUPDF_SETUP_PY_LIMITED_API=0 uv pip install --python /opt/codex/bin/python \
         --no-cache --compile-bytecode -r requirements.txt \
     && uv pip install --python /opt/codex/bin/python --no-cache --no-deps \
@@ -96,15 +97,15 @@ RUN uv export --frozen --no-default-groups --no-emit-project -o requirements.txt
 # English: LANGUAGE_CODE is en-us and nothing activates another language.
 # hadolint ignore=SC2016
 RUN set -eux \
-    && find /opt/codex -type f \( -name '*.so' -o -name '*.so.*' \) \
-        -exec strip --strip-unneeded {} + \
-    && find /opt/codex -name '*.pyi' -delete \
-    && rm -rf /opt/codex/lib/python3.14/site-packages/pycountry/locales \
-    && find /opt/codex/lib/python3.14/site-packages -type d -name locale -prune \
-        -exec sh -c 'for d in "$1"/*/; do case "$(basename "$d")" in en|__pycache__) ;; *) rm -rf "$d";; esac; done' _ {} \;
+  && find /opt/codex -type f \( -name '*.so' -o -name '*.so.*' \) \
+  -exec strip --strip-unneeded {} + \
+  && find /opt/codex -name '*.pyi' -delete \
+  && rm -rf /opt/codex/lib/python3.15/site-packages/pycountry/locales \
+  && find /opt/codex/lib/python3.15/site-packages -type d -name locale -prune \
+  -exec sh -c 'for d in "$1"/*/; do case "$(basename "$d")" in en|__pycache__) ;; *) rm -rf "$d";; esac; done' _ {} \;
 
 # ---- Stage 4: final (production image) ------------------------------------
-FROM ghcr.io/ajslater/python-debian:3.14.6-slim-trixie_0 AS final
+FROM ghcr.io/ajslater/python-debian:3.15.0-slim-trixie_0 AS final
 ARG CODEX_VERSION=dev
 LABEL org.opencontainers.image.title="Codex" \
     org.opencontainers.image.description="Codex Comic Server" \

NEWS.md

@@ -6,6 +6,19 @@ width: 128px;
 border-radius: 128px;
 " />
 
+## v2.5.5
+
+- Features
+    - `csrf_trusted_origins` setting for CSRF 403s behind a reverse proxy.
+    - Docker images now use Python 3.15
+- Fixes
+    - Online tagging matches saved for review by 2.5.3 no longer break the
+      review list and scan status with "No module named 'numpy'". They are
+      dropped, so those comics need tagging again.
+    - Renamed comics no longer contain colons or other characters Windows and
+      SMB shares can't store.
+    - A Metron API key is no longer overridden by a `~/.netrc` login.
+
 ## v2.5.4
 
 - Features

README.md

@@ -471,6 +471,11 @@ present.
 # websockets = true
 # HTTP path prefix for codex (e.g. "/codex" for reverse proxy sub-path)
 # url_path_prefix = ""
+# Public origins accepted for CSRF when a reverse proxy serves Codex under
+# another scheme or host than Codex sees (e.g. https in front of http).
+# First make sure the proxy sends X-Forwarded-Proto and X-Forwarded-Host.
+# A correctly configured proxy does, and then you shouldn't need this.
+# csrf_trusted_origins = ["https://comics.example.com"]
 
 # [logging]
 # Log level: TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
@@ -569,6 +574,9 @@ Environment variables override values set in the TOML config file.
   Default true.
 - `GRANIAN_URL_PATH_PREFIX` HTTP path prefix for codex (e.g. "/codex" for
   reverse proxy sub-path). Defaults to "".
+- `CODEX_CSRF_TRUSTED_ORIGINS` Comma-separated public origins (e.g.
+  `https://comics.example.com`) accepted for CSRF behind a reverse proxy. See
+  [CSRF 403 behind a proxy](#csrf-403-behind-a-proxy). Defaults to none.
 
 ##### Repair
 
@@ -697,6 +705,28 @@ of the `/codex` location with `auth_request`, exempt the API the way Codex's own
 examples do (`location /codex/api { auth_request off; ... }`); the `^~` note
 above is what keeps the static assets reachable.
 
+#### CSRF 403 behind a proxy
+
+If logging in or saving changes fails with a 403 "CSRF Failed" error behind a
+reverse proxy, first make sure the proxy sends `X-Forwarded-Proto` and
+`X-Forwarded-Host` (the nginx example above does). Codex compares them with the
+browser's `Origin` header, so a correctly configured proxy ordinarily needs no
+CSRF setting at all. Only if the proxy can't send them, or the error persists,
+add the public origin the browser uses to `config/codex.toml`:
+
+```toml
+[server]
+csrf_trusted_origins = ["https://comics.example.com"]
+```
+
+or set `CODEX_CSRF_TRUSTED_ORIGINS="https://comics.example.com"` (comma
+separated for more than one). An origin is `scheme://host[:port]` with no path;
+`https://*.example.com` trusts every subdomain.
+
+Do not remove Django's `CsrfViewMiddleware` to work around the error. The API
+enforces CSRF through Django REST Framework anyway, so removing it doesn't fix
+the API, and it strips CSRF protection from Codex's other pages.
+
 #### Preserving the Codex Server Header
 
 Codex identifies itself with a `Server: codex/<version>` response header, which

bin/_lib.sh

@@ -17,11 +17,16 @@ is_darwin() {
 }
 
 # Succeed when the tool is on PATH. Otherwise say so and how to install it, and
-# fail, so a caller can skip that tool visibly instead of silently.
+# fail, so a caller can skip that tool visibly instead of silently. In CI (CI
+# set, as GitHub sets it) a missing tool is an error instead, so a green CI
+# run means every tool ran.
 need() {
   if command -v "$1" >/dev/null 2>&1; then
     return 0
   fi
+  if [[ -n ${CI:-} ]]; then
+    die "$1 not installed. CI must install it: brew install $1, or add it to the Dockerfile's CI stage"
+  fi
   echo "skipped: $1 not installed (brew install $1)" >&2
   return 1
 }