243 lines
4.6 KiB
Markdown
243 lines
4.6 KiB
Markdown
# 🚀 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! 🏠✨**
|