From 447861feed069ccdb222dd68b65c2dbc5f7ff711 Mon Sep 17 00:00:00 2001
From: jessikitty <jess.rogerson.29@outlook.com>
Date: Thu, 18 Dec 2025 16:35:10 +1100
Subject: [PATCH] Add quick setup guide for easy installation

---
 SETUP.md | 242 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 242 insertions(+)
 create mode 100644 SETUP.md

diff --git a/SETUP.md b/SETUP.md
new file mode 100644
index 0000000..86f677d
--- /dev/null
+++ b/SETUP.md
@@ -0,0 +1,242 @@
+# 🚀 Family Hub - Quick Setup Guide
+
+This guide will get you up and running with Family Hub in minutes.
+
+---
+
+## Prerequisites
+
+- **Docker & Docker Compose** (Recommended)
+  - OR Python 3.11+ and Node.js 18+ for local development
+
+---
+
+## Option 1: Docker Setup (Recommended) 🐳
+
+### 1. Clone the Repository
+```bash
+git clone https://gitea.hideawaygaming.com.au/jessikitty/family-hub.git
+cd family-hub
+```
+
+### 2. Configure Environment
+```bash
+# Backend environment
+cp backend/.env.example backend/.env
+
+# Edit backend/.env and set your SECRET_KEY
+nano backend/.env  # or use your preferred editor
+```
+
+### 3. Start Services
+```bash
+docker-compose up -d
+```
+
+### 4. Initialize Database (First Run Only)
+```bash
+docker-compose exec backend python init_db.py
+```
+
+This creates your family member accounts:
+- **Lou** (username: `lou`, password: `changeme123`)
+- **Jess** (username: `jess`, password: `changeme123`) - Admin
+- **William** (username: `william`, password: `changeme123`)
+- **Xander** (username: `xander`, password: `changeme123`)
+- **Bella** (username: `bella`, password: `changeme123`)
+
+⚠️ **Change these passwords after first login!**
+
+### 5. Access the Application
+- **Frontend:** http://localhost:5173
+- **Backend API:** http://localhost:8000
+- **API Docs:** http://localhost:8000/docs
+
+### 6. Stop Services
+```bash
+docker-compose down
+```
+
+---
+
+## Option 2: Local Development Setup 💻
+
+### Backend Setup
+
+```bash
+# 1. Navigate to backend
+cd backend
+
+# 2. Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# 3. Install dependencies
+pip install -r requirements.txt
+
+# 4. Configure environment
+cp .env.example .env
+# Edit .env with your settings
+
+# 5. Initialize database
+python init_db.py
+
+# 6. Run development server
+uvicorn app.main:app --reload
+```
+
+Backend available at: **http://localhost:8000**
+
+### Frontend Setup
+
+```bash
+# 1. Navigate to frontend (in new terminal)
+cd frontend
+
+# 2. Install dependencies
+npm install
+
+# 3. Run development server
+npm run dev
+```
+
+Frontend available at: **http://localhost:5173**
+
+---
+
+## Verify Installation ✅
+
+1. **Check Backend Health**
+```bash
+curl http://localhost:8000/health
+```
+Should return: `{"status":"healthy","service":"family-hub"}`
+
+2. **Check API Documentation**
+Visit: http://localhost:8000/docs
+
+3. **Login to Frontend**
+Visit: http://localhost:5173
+Login with: `jess` / `changeme123`
+
+---
+
+## Next Steps 🎯
+
+1. **Change default passwords** for all users
+2. **Explore the API documentation** at `/docs`
+3. **Check PROJECT_ROADMAP.md** to see development progress
+4. **Start using the chore system** (Phase 2 features coming soon!)
+
+---
+
+## Troubleshooting 🔧
+
+### Docker Issues
+
+**Port already in use:**
+```bash
+# Check what's using the ports
+sudo lsof -i :8000
+sudo lsof -i :5173
+
+# Or change ports in docker-compose.yml
+```
+
+**Database not initializing:**
+```bash
+# Restart and rebuild
+docker-compose down -v
+docker-compose up -d --build
+docker-compose exec backend python init_db.py
+```
+
+### Local Development Issues
+
+**Module not found:**
+```bash
+# Ensure virtual environment is activated
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+
+# Reinstall dependencies
+pip install -r requirements.txt
+```
+
+**Database errors:**
+```bash
+# Remove old database and reinitialize
+rm family_hub.db
+python init_db.py
+```
+
+**Frontend not starting:**
+```bash
+# Clear node modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+---
+
+## Configuration 🔧
+
+### Backend (.env)
+```env
+# Required
+SECRET_KEY=your-secret-key-here
+DATABASE_URL=sqlite:///./family_hub.db
+
+# Optional integrations
+GOOGLE_CLIENT_ID=your-google-client-id
+MEALIE_API_URL=http://your-mealie-instance
+HOME_ASSISTANT_URL=http://your-ha-instance
+```
+
+### Frontend (.env)
+```env
+VITE_API_URL=http://localhost:8000
+```
+
+---
+
+## Default User Credentials
+
+| User | Username | Password | Role |
+|------|----------|----------|------|
+| Lou | `lou` | `changeme123` | User |
+| Jess | `jess` | `changeme123` | Admin |
+| William | `william` | `changeme123` | User |
+| Xander | `xander` | `changeme123` | User |
+| Bella | `bella` | `changeme123` | User |
+
+---
+
+## Development Commands
+
+```bash
+# Run backend tests
+cd backend && pytest
+
+# Run frontend tests  
+cd frontend && npm test
+
+# View logs (Docker)
+docker-compose logs -f backend
+docker-compose logs -f frontend
+
+# Rebuild containers
+docker-compose up -d --build
+```
+
+---
+
+## Need Help? 🆘
+
+- Check **PROJECT_ROADMAP.md** for current development status
+- Review **README.md** for detailed documentation
+- Check API docs at http://localhost:8000/docs
+- Open an issue in Gitea
+
+---
+
+**You're all set! Start managing your family's chores, calendar, and meals! 🏠✨**