Files
derekcandClaude Opus 5.5 d357d6b885 Add 2026.10 release notes and update README
- release-notes/2026.10.md: version changes, code/config changes,
  upgrade and rollback steps, and test results for the October 2026
  dependency upgrades
- README: add Upgrading section, component versions, Other purchases
  feature, session token row in Security; fix API docs location
  (not exposed via nginx); add ntfy.py, favicon.svg, release-notes/
  to project structure

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-27 23:20:04 -07:00

5.1 KiB
Raw Permalink Blame History

Yolkbook 2026.10 Release Notes

Release date: 2026-10-27

This release brings every dependency up to date, replaces the unmaintained python-jose library with PyJWT, and moves the database from MySQL 8.0 (end of life) to the MySQL 8.4 LTS series. No features changed, and existing data and login sessions carry over.

Upgrading an existing install? Read Upgrade instructions first. The MySQL 8.4 upgrade is one-way, so back up your database before you start.

Version changes

Runtime and infrastructure

Component Before After Notes
Python (API base image) 3.12-slim (3.12.13) 3.14-slim (3.14.10) 3.12 only receives security fixes now
MySQL 8.0.46 8.4.13 LTS MySQL 8.0 has reached end of life
Nginx 1.30.2-alpine 1.30.6-alpine Latest stable branch
Chart.js (CDN) 4.5.1 4.6.1 New SRI hash

Python packages (backend/requirements.txt)

Package Before After Notes
fastapi 0.136.3 0.162.0 Starlette 1.1.0 → 1.10.0 comes with it
uvicorn 0.48.0 0.54.0
sqlalchemy 2.0.50 2.1.6 No code changes needed
pydantic 2.13.4 2.14.1
pymysql 1.2.0 1.2.3
cryptography 48.0.0 50.0.2
python-jose[cryptography] 3.5.0 removed Replaced with PyJWT (see below)
pyjwt — 2.15.1 New
bcrypt 5.0.0 5.0.0 Already current
httpx 0.28.1 0.28.1 Already current

Unpinned packages these depend on (certifi, idna, anyio, cffi, pip, and others) were refreshed by rebuilding the image.

Code and configuration changes

  • python-jose replaced with PyJWT (backend/auth.py). python-jose is barely maintained, while PyJWT is the actively maintained standard. Only the import and the caught exception type changed (JWTError → InvalidTokenError). Tokens are still HS256-signed with JWT_SECRET, so tokens issued before the upgrade stay valid and nobody is logged out.
  • Subresource Integrity added to the Monthly Summary page (nginx/html/summary.html). The Chart.js <script> tag on this page had no integrity hash, unlike the dashboard. Both pages now load Chart.js 4.6.1 with the same SHA-384 hash.
  • Longer MySQL healthcheck start period (docker-compose.yml). start_period went from 30s to 180s. The first start after a MySQL version bump runs a one-time data upgrade (about 90 seconds for 8.0 → 8.4). With the old setting, Docker Compose marked the database unhealthy during the upgrade and never started the API. Normal startups aren't slowed, because the healthcheck passes as soon as MySQL is ready.
  • README now lists component versions, has an upgrade guide, and gives the correct location of the interactive API docs.

Upgrade instructions

These steps apply to existing installs on MySQL 8.0. Fresh installs need no special steps.

  1. Back up the database (required, because MySQL 8.4 can't be downgraded in place):
    docker compose exec -T db sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --routines --triggers --databases "$MYSQL_DATABASE"' > yolkbook-backup.sql
    
  2. Pull the update:
    git pull
    
  3. Rebuild and restart:
    docker compose build --pull api
    docker compose pull
    docker compose up -d
    
  4. Wait for the first start. MySQL upgrades its data files in place, which takes about 1–2 minutes. The API starts once the database reports healthy. You can follow along with docker compose logs -f db and look for Server upgrade from '80046' to '80413' completed.
  5. Check it: docker compose ps should show all three containers healthy or up. Log in and confirm your data is there.

Rollback: if something goes wrong, check out the previous release, remove the mysql_data volume, start the stack on MySQL 8.0, and restore the backup from step 1:

docker compose exec -T db sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD"' < yolkbook-backup.sql

Testing

Before deploying, the upgrade was tested on an isolated copy of the stack loaded with a backup of production data:

  • An automated smoke test of every API endpoint passed with no failures: login and lockout, create/edit/delete for eggs, flock, feed, and other purchases, validation errors, admin user management, impersonation, password and timezone changes, logout, disabled-account handling, and rejection of tampered tokens.
  • Every list endpoint (eggs, flock, feed, other purchases) and every stats endpoint (dashboard, monthly, budget) returned identical output before and after the upgrade.
  • A token issued by python-jose was accepted after the switch to PyJWT.
  • All pages and static assets loaded through nginx.
  • After the production deploy, record counts and totals for every table matched the numbers taken just before the deploy.

Commits

  • 8f32a39 Bump low-risk dependencies: uvicorn, pymysql, cryptography, pydantic, nginx, Chart.js
  • 2382289 Major dependency upgrades: Python 3.14, FastAPI, SQLAlchemy 2.1, PyJWT, MySQL 8.4
  • 896be8f Extend MySQL healthcheck start_period to 180s