family-hub/SETUP.md

🚀 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

git clone https://gitea.hideawaygaming.com.au/jessikitty/family-hub.git
cd family-hub

2. Configure Environment

# 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

docker-compose up -d

4. Initialize Database (First Run Only)

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

docker-compose down

---

Option 2: Local Development Setup 💻

Backend Setup

# 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

# 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

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:

# Check what's using the ports
sudo lsof -i :8000
sudo lsof -i :5173

# Or change ports in docker-compose.yml

Database not initializing:

# 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:

# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Reinstall dependencies
pip install -r requirements.txt

Database errors:

# Remove old database and reinitialize
rm family_hub.db
python init_db.py

Frontend not starting:

# Clear node modules and reinstall
rm -rf node_modules package-lock.json
npm install

---

Configuration 🔧

Backend (.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)

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

# 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! 🏠✨