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]>
This commit is contained in:
1 parent
896be8fbe9
commit
d357d6b885
2 files changed
+115
-7
No files matched your search
@@ -8,7 +8,8 @@ A self-hosted, multi-user web app for backyard chicken keepers to track egg prod
|
||||
- **Daily log** — record egg collections with one entry per day; includes full collection history with date filtering, edit, and delete below the form
|
||||
- **Flock management** — track changes to your flock size over time so per-hen averages stay accurate
|
||||
- **Feed tracking** — log feed purchases (bags + price per bag)
|
||||
- **Budget** — cost per egg and cost per dozen, all-time and over the last 30 days
|
||||
- **Other purchases** — log other flock expenses (bedding, snacks, supplies) so they count toward your costs
|
||||
- **Budget** — feed and other costs, cost per egg, and cost per dozen, all-time and over the last 30 days
|
||||
- **Monthly summary** — month-by-month breakdown of production, averages, feed cost, and cost per egg
|
||||
- **Multi-user** — each user has their own isolated data; self-registration on the login page
|
||||
- **Admin panel** — view all users, reset passwords, disable/enable accounts, delete accounts, and log in as any user
|
||||
@@ -18,13 +19,15 @@ A self-hosted, multi-user web app for backyard chicken keepers to track egg prod
|
||||
## Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|----------|-------------------------|
|
||||
| Frontend | Vanilla HTML/CSS/JS |
|
||||
| Backend | FastAPI (Python) |
|
||||
|----------|-----------------------------------------------------|
|
||||
| Frontend | Vanilla HTML/CSS/JS, Chart.js 4.6 |
|
||||
| Backend | Python 3.14, FastAPI, SQLAlchemy 2.1, PyJWT, bcrypt |
|
||||
| Database | MySQL 8.4 LTS |
|
||||
| Server | Nginx (static + proxy) |
|
||||
| Server | Nginx 1.30 (static + proxy) |
|
||||
| Runtime | Docker Compose |
|
||||
|
||||
Exact versions are pinned in `backend/requirements.txt`, `backend/Dockerfile`, and `docker-compose.yml`. See [`release-notes/`](release-notes/) for what changed in each release.
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
@@ -77,6 +80,23 @@ A self-hosted, multi-user web app for backyard chicken keepers to track egg prod
|
||||
|
||||
The database schema is applied automatically on first start via `mysql/init.sql`. The admin user is created (or synced) automatically every time the API starts.
|
||||
|
||||
## Upgrading
|
||||
|
||||
1. Read the release notes in [`release-notes/`](release-notes/) for the version you're moving to. Some releases have extra steps.
|
||||
2. Back up the database:
|
||||
```bash
|
||||
docker compose exec -T db sh -c 'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --routines --triggers --databases "$MYSQL_DATABASE"' > yolkbook-backup.sql
|
||||
```
|
||||
3. Pull the update, then rebuild and restart:
|
||||
```bash
|
||||
git pull
|
||||
docker compose build --pull api
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
When the MySQL version changes, the first start runs a one-time data upgrade, and the API waits until it finishes. Going from MySQL 8.0 to 8.4 takes about 1–2 minutes, and the change is one-way: to go back, you have to restore from your backup. Follow progress with `docker compose logs -f db`.
|
||||
|
||||
## Authentication
|
||||
|
||||
- **Login / Register** — the landing page (`/login`) has both a sign-in form and a self-registration link.
|
||||
@@ -127,11 +147,12 @@ The gear icon (⚙) in the top-right nav opens the Settings panel:
|
||||
| Authentication | HttpOnly + Secure + SameSite=Strict session cookie; no token in JS-accessible storage |
|
||||
| CSRF protection | SameSite=Strict cookie prevents cross-site request forgery without explicit tokens |
|
||||
| Password hashing | bcrypt |
|
||||
| Session tokens | HS256-signed JWT (PyJWT), 30-day expiry |
|
||||
| CORS | Locked to same origin by default; configurable via `ALLOWED_ORIGINS` |
|
||||
| Rate limiting | Login: 5 req/min · Register: 3 req/min · Admin endpoints: 10 req/min (nginx) |
|
||||
| Login lockout | Account locked for 15 minutes after 5 consecutive failed attempts |
|
||||
| Security headers | X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy, Content-Security-Policy |
|
||||
| Subresource Integrity | Chart.js CDN script pinned with SHA-384 hash |
|
||||
| Subresource Integrity | Chart.js CDN script pinned with a SHA-384 hash on every page that loads it |
|
||||
| Input validation | Server-side via Pydantic; all user-rendered content HTML-escaped |
|
||||
| SQL injection | SQLAlchemy ORM with parameterized queries throughout |
|
||||
| Container security | API runs as non-root user; all volume mounts read-only except database |
|
||||
@@ -156,7 +177,7 @@ All existing data will be automatically assigned to the admin account on first s
|
||||
|
||||
## API
|
||||
|
||||
The FastAPI backend is available at `/api`. Interactive docs (Swagger UI) are at `/api/docs`.
|
||||
The FastAPI backend is available at `/api`. The interactive docs (Swagger UI) aren't exposed through nginx. FastAPI serves them inside the API container at `http://localhost:8000/docs`.
|
||||
|
||||
| Prefix | Description |
|
||||
|------------------|----------------------------------------------------|
|
||||
@@ -180,6 +201,7 @@ yolkbook/
|
||||
│ ├── models.py # SQLAlchemy models
|
||||
│ ├── schemas.py # Pydantic schemas
|
||||
│ ├── database.py # DB connection
|
||||
│ ├── ntfy.py # ntfy push notification helper
|
||||
│ ├── routers/
|
||||
│ │ ├── auth_router.py # /api/auth — login, logout, register, settings
|
||||
│ │ ├── admin.py # /api/admin — user management + impersonation
|
||||
@@ -201,6 +223,7 @@ yolkbook/
|
||||
│ │ ├── login.html
|
||||
│ │ ├── 404.html
|
||||
│ │ ├── 50x.html
|
||||
│ │ ├── favicon.svg
|
||||
│ │ ├── js/
|
||||
│ │ │ ├── api.js # Shared fetch helpers
|
||||
│ │ │ ├── auth.js # Auth utilities, nav, settings modal
|
||||
@@ -217,6 +240,7 @@ yolkbook/
|
||||
├── mysql/
|
||||
│ ├── init.sql # Schema for fresh installs
|
||||
│ └── migrate_v2.sql # Migration for pre-multi-user installs
|
||||
├── release-notes/ # Per-release change logs (e.g. 2026.10.md)
|
||||
├── .env.example # Template — copy to .env and fill in values
|
||||
├── docker-compose.yml
|
||||
└── .env # Secrets — not committed
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# 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
|
||||
Reference in new issue
Block a user