eggtracker/README.md

Eggtracker

A self-hosted 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, average eggs per day and per hen
• Daily log — record egg collections with one entry per day
• History — browse, edit, and delete past egg collection records
• 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

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

Setup

1. Clone the repo:

   git clone https://git.chns.tech/CooperandGoodman/eggtracker.git
   cd eggtracker
   

2. Create a .env file in the project root:

   MYSQL_ROOT_PASSWORD=your_root_password
   MYSQL_DATABASE=eggtracker
   MYSQL_USER=eggtracker
   MYSQL_PASSWORD=your_password
   

3. Start the stack:

   docker compose up -d
   

4. Open your browser at http://localhost:8056

The database schema is applied automatically on first start via mysql/init.sql.

API

The FastAPI backend is available at /api. Interactive docs (Swagger UI) are at /api/docs.

Prefix	Description
/api/eggs	Egg collection records
/api/flock	Flock size history
/api/feed	Feed purchase records
/api/stats	Dashboard, budget, and monthly summary stats

Project Structure

eggtracker/
├── backend/
│   ├── main.py          # FastAPI app entry point
│   ├── models.py        # SQLAlchemy models
│   ├── schemas.py       # Pydantic schemas
│   ├── database.py      # DB connection
│   ├── routers/         # Route handlers (eggs, flock, feed, stats)
│   ├── requirements.txt
│   └── Dockerfile
├── nginx/
│   ├── html/            # Frontend (HTML, CSS, JS)
│   └── nginx.conf
├── mysql/
│   └── init.sql         # Schema applied on first start
├── docker-compose.yml
└── .env                 # Secrets — not committed