diff --git a/README.md b/README.md index ff5fbcd..ff872d6 100644 --- a/README.md +++ b/README.md @@ -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 @@ -17,13 +18,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) | -| Database | MySQL 8.4 LTS | -| Server | Nginx (static + proxy) | -| Runtime | Docker Compose | +| Layer | Technology | +|----------|-----------------------------------------------------| +| 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 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 @@ -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 diff --git a/release-notes/2026.10.md b/release-notes/2026.10.md new file mode 100644 index 0000000..674a00d --- /dev/null +++ b/release-notes/2026.10.md @@ -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 `