yolkbook/README.md

# 🥚 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)
- **Budget** — 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

## Tech Stack

| Layer    | Technology              |
|----------|-------------------------|
| Frontend | Vanilla HTML/CSS/JS     |
| Backend  | FastAPI (Python)        |
| Database | MySQL 8.0               |
| Server   | Nginx (static + proxy)  |
| Runtime  | Docker Compose          |

## 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/CooperandGoodman/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.

## 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 |
| 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 |
| 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 |
| 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 |
| 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`. Interactive docs (Swagger UI) are at `/api/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
│   ├── 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
│   │   ├── 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
├── .env.example          # Template — copy to .env and fill in values
├── docker-compose.yml
└── .env                  # Secrets — not committed
```