248 lines
12 KiB
Markdown
248 lines
12 KiB
Markdown
# 🥚 Yolkbook
|
||
|
||
A self-hosted, multi-user web app for backyard chicken keepers to track egg production, flock size, feed costs, and egg economics over time.
|
||
|
||
## Features
|
||
|
||
- **Dashboard** — at-a-glance stats: total eggs, 7/30-day totals, averages (green), flock size (orange), cost per egg and per dozen
|
||
- **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)
|
||
- **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
|
||
- **Timezone support** — each user sets their own timezone so dates and stat windows are always accurate
|
||
- **Push notifications** — optional ntfy alerts for security events: new registrations, admin logins, account lockouts, user changes, and impersonation
|
||
|
||
## Tech Stack
|
||
|
||
| 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
|
||
|
||
### Prerequisites
|
||
|
||
- Docker and Docker Compose
|
||
- A reverse proxy with HTTPS (e.g. Nginx Proxy Manager) — required for secure cookie authentication
|
||
|
||
### Setup
|
||
|
||
1. Clone the repo:
|
||
```bash
|
||
git clone https://git.chns.tech/CHNS/yolkbook.git
|
||
cd yolkbook
|
||
```
|
||
|
||
2. Copy `.env.example` to `.env` and fill in your values:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Required variables:
|
||
|
||
| Variable | Description |
|
||
|----------|-------------|
|
||
| `MYSQL_ROOT_PASSWORD` | MySQL root password — generate with `openssl rand -hex 16` |
|
||
| `MYSQL_DATABASE` | Database name (default: `eggtracker`) |
|
||
| `MYSQL_USER` | MySQL app username |
|
||
| `MYSQL_PASSWORD` | MySQL app user password |
|
||
| `ADMIN_USERNAME` | Username for the built-in admin account |
|
||
| `ADMIN_PASSWORD` | Password for the built-in admin account |
|
||
| `JWT_SECRET` | JWT signing secret — generate with `openssl rand -hex 32` |
|
||
|
||
Optional variables (with defaults):
|
||
|
||
| Variable | Default | Description |
|
||
|----------|---------|-------------|
|
||
| `SECURE_COOKIES` | `true` | Set to `false` for local HTTP testing only; leave `true` when behind HTTPS |
|
||
| `ALLOWED_ORIGINS` | *(empty)* | Comma-separated list of external origins allowed to call the API. Leave empty if accessed only through the bundled nginx frontend. |
|
||
| `NTFY_URL` | *(empty)* | ntfy topic URL for push notifications (e.g. `https://ntfy.sh/your-secret-topic`). Leave empty to disable. |
|
||
| `NTFY_TOKEN` | *(empty)* | Bearer token for authenticated ntfy topics. Leave empty if your topic is public or not needed. |
|
||
|
||
3. Start the stack:
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
4. Point your reverse proxy at port `8056` with HTTPS enabled.
|
||
|
||
5. Open your browser at `https://<your-domain>/login` and sign in with the admin credentials you set in `.env`.
|
||
|
||
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.
|
||
- **Sessions** — after login, a session cookie is set by the server. It is `HttpOnly` (inaccessible to JavaScript), `Secure` (HTTPS only), and `SameSite=Strict` (CSRF protection). Valid for 30 days.
|
||
- **Logout** — the `/api/auth/logout` endpoint clears the session cookie server-side.
|
||
- **Admin password** — always sourced from the `ADMIN_PASSWORD` env var. Changing it in `.env` and restarting updates the admin's password automatically.
|
||
|
||
## Admin Panel
|
||
|
||
Accessible at `/admin` for admin accounts. Features:
|
||
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| Reset password | Set a new password for any user |
|
||
| Disable / Enable | Block or restore a user's access |
|
||
| Delete | Permanently remove a user and all their data |
|
||
| Login As | Impersonate a user to view or edit their data directly |
|
||
|
||
When impersonating a user, an amber banner appears in the nav with a **Return to Admin** button. The original admin session is preserved server-side — no admin credentials are stored in the browser during impersonation.
|
||
|
||
## Push Notifications
|
||
|
||
Yolkbook can send alerts via [ntfy](https://ntfy.sh) for security-relevant events. Set `NTFY_URL` in `.env` to enable.
|
||
|
||
| Event | Priority |
|
||
|-------|----------|
|
||
| New user registered | default |
|
||
| Admin login | high |
|
||
| Account locked after failed attempts | urgent |
|
||
| Login attempt on locked account | high |
|
||
| User disabled | high |
|
||
| User deleted | urgent |
|
||
| Admin impersonation started | high |
|
||
|
||
Use `https://ntfy.sh/your-secret-topic` for the hosted service or a self-hosted ntfy URL. Set `NTFY_TOKEN` if your topic requires authentication. Notifications are fire-and-forget — a failed delivery is logged but never interrupts a request.
|
||
|
||
## User Settings
|
||
|
||
The gear icon (⚙) in the top-right nav opens the Settings panel:
|
||
|
||
- **Timezone** — choose from a full list of IANA timezones or click *Detect automatically*. Affects what "today" is when pre-filling date fields and the 30-day/7-day windows on the dashboard and budget pages.
|
||
- **Change Password** — update your own password (requires current password).
|
||
|
||
## Security
|
||
|
||
| Feature | Details |
|
||
|---------|---------|
|
||
| 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 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 |
|
||
|
||
## Footer
|
||
|
||
All authenticated pages include a footer with a **Created by: [CHNS.tech](https://chns.tech)** credit and a Buy Me a Coffee button linking to [buymeacoffee.com/CHNS](https://www.buymeacoffee.com/CHNS).
|
||
|
||
## Migrating an Existing Install (pre-multi-user)
|
||
|
||
If you have an existing single-user install, run the migration script before rebuilding:
|
||
|
||
```bash
|
||
# 1. Run the migration while the database is still running
|
||
docker compose exec db mysql -u root -p"${MYSQL_ROOT_PASSWORD}" eggtracker < mysql/migrate_v2.sql
|
||
|
||
# 2. Rebuild and restart
|
||
docker compose up -d --build
|
||
```
|
||
|
||
All existing data will be automatically assigned to the admin account on first startup.
|
||
|
||
## API
|
||
|
||
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 |
|
||
|------------------|----------------------------------------------------|
|
||
| `/api/auth` | Login, logout, register, change password, timezone |
|
||
| `/api/admin` | User management (admin only) |
|
||
| `/api/eggs` | Egg collection records |
|
||
| `/api/flock` | Flock size history |
|
||
| `/api/feed` | Feed purchase records |
|
||
| `/api/other` | Other purchases (bedding, snacks, etc.) |
|
||
| `/api/stats` | Dashboard, budget, and monthly summary |
|
||
|
||
All data endpoints require an authenticated session cookie. Requests are automatically authenticated by the browser — no `Authorization` header is needed.
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
yolkbook/
|
||
├── backend/
|
||
│ ├── main.py # FastAPI app entry point + startup seeding
|
||
│ ├── auth.py # JWT utilities, password hashing, cookie helpers, auth dependencies
|
||
│ ├── 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
|
||
│ │ ├── eggs.py
|
||
│ │ ├── flock.py
|
||
│ │ ├── feed.py
|
||
│ │ ├── other.py
|
||
│ │ └── stats.py
|
||
│ ├── requirements.txt
|
||
│ └── Dockerfile
|
||
├── nginx/
|
||
│ ├── html/ # Frontend (HTML, CSS, JS)
|
||
│ │ ├── index.html # Dashboard
|
||
│ │ ├── log.html # Log Eggs + full collection history
|
||
│ │ ├── flock.html # Flock management
|
||
│ │ ├── budget.html # Budget / cost analysis
|
||
│ │ ├── summary.html # Monthly summary
|
||
│ │ ├── admin.html # Admin panel
|
||
│ │ ├── login.html
|
||
│ │ ├── 404.html
|
||
│ │ ├── 50x.html
|
||
│ │ ├── favicon.svg
|
||
│ │ ├── js/
|
||
│ │ │ ├── api.js # Shared fetch helpers
|
||
│ │ │ ├── auth.js # Auth utilities, nav, settings modal
|
||
│ │ │ ├── login.js # Login/register page logic
|
||
│ │ │ ├── dashboard.js
|
||
│ │ │ ├── log.js # Egg logging interface
|
||
│ │ │ ├── history.js # Collection history table (used on log page)
|
||
│ │ │ ├── flock.js
|
||
│ │ │ ├── budget.js
|
||
│ │ │ ├── summary.js
|
||
│ │ │ └── admin.js # Admin panel
|
||
│ │ └── css/style.css
|
||
│ └── nginx.conf
|
||
├── 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
|
||
```
|