- 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]>
85 lines
5.1 KiB
Markdown
85 lines
5.1 KiB
Markdown
# 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](#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):
|
||
```bash
|
||
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:**
|
||
```bash
|
||
git pull
|
||
```
|
||
3. **Rebuild and restart:**
|
||
```bash
|
||
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:
|
||
```bash
|
||
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
|