Meal-Planner/docs/RUNNING.md

# Running the Meal Planner

## Prerequisites

- Docker and Docker Compose
- Git
- SendGrid account (for email)
- Lucky California store access (for scraping)

## Environment Setup

### 1. Clone Repository

```bash
git clone <repository-url>
cd MealPlanner
```

### 2. Create Environment File

```bash
cp .env.example .env
```

Edit `.env` with your values:

```bash
# Database
POSTGRES_PASSWORD=your_secure_password

# SendGrid
SENDGRID_API_KEY=SG.your_sendgrid_api_key

# Family Emails
FAMILY_EMAIL_1=you@example.com
FAMILY_EMAIL_2=spouse@example.com

# Lucky California (for scraping)
LUCKY_CA_URL=https://www.luckyncal.com

# AI Images (optional)
AI_IMAGE_ENABLED=false
AI_IMAGE_PROVIDER=openai
AI_IMAGE_API_KEY=sk-your-key
```

### 3. Create SSL Certificates (for remote access)

```bash
mkdir -p nginx/ssl
# Option 1: Let's Encrypt with Certbot
certbot certonly --nginx -d your-domain.com

# Option 2: Self-signed for local testing
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout nginx/ssl/key.pem -out nginx/ssl/cert.pem
```

## Starting Services

### Local Development

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

# Stop all services
docker-compose down
```

### Production Deployment

```bash
# Start with production settings
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Check service status
docker-compose ps

# View resource usage
docker stats
```

## Accessing the Application

### Local Access

- **Web UI**: http://localhost:3000
- **API**: http://localhost:8000
- **API Docs**: http://localhost:8000/docs

### Remote Access (with reverse proxy)

Configure your domain and SSL in nginx/nginx.conf, then access via:
- **Web UI**: https://your-domain.com
- **API**: https://your-domain.com/api

## Database Management

### Initial Migration

```bash
# Run migrations
docker-compose exec backend alembic upgrade head

# Check current migration
docker-compose exec backend alembic current

# Create new migration after model changes
docker-compose exec backend alembic revision --autogenerate -m "Description"
```

### Backup Database

```bash
# Backup to file
docker-compose exec db pg_dump -U mealplanner mealplanner > backup_$(date +%Y%m%d).sql

# Restore from backup
cat backup_20240101.sql | docker-compose exec -T db psql -U mealplanner mealplanner
```

### Reset Database

```bash
# Danger: Drops and recreates all data
docker-compose down -v
docker-compose up -d
docker-compose exec backend alembic upgrade head
```

## Scraping

### Manual Scrape Trigger

```bash
# Scrape Lucky California weekly ad
curl -X POST http://localhost:8000/api/admin/scrape \
  -H "Content-Type: application/json" \
  -d '{"source": "lucky_california", "type": "weekly_ad"}'
```

### Check Scrape Logs

```bash
# View recent scrape operations
curl http://localhost:8000/api/admin/logs?limit=10
```

### Scheduling

Scrape runs automatically:
- Weekly: Sunday at 8 PM (before meal planning)
- Daily: 6 AM (price updates)

## Email Testing

### Test Email Send

```bash
# Send test email
curl -X POST http://localhost:8000/api/admin/test-email \
  -H "Content-Type: application/json" \
  -d '{"to": "test@example.com", "template": "meal_proposal"}'
```

### View Email Logs

```bash
curl http://localhost:8000/api/admin/email-logs
```

## Troubleshooting

### Backend Won't Start

```bash
# Check logs
docker-compose logs backend

# Common issues:
# - Database not ready: wait for db to be healthy
# - Port conflict: check if port 8000 is in use
# - Missing env vars: verify .env file exists and is valid
```

### Frontend Build Fails

```bash
# Check for Node version issues
node --version  # Should be 18+

# Clear cache and rebuild
docker-compose exec frontend npm cache clean --force
docker-compose exec frontend rm -rf node_modules package-lock.json
docker-compose exec frontend npm install
```

### Database Connection Errors

```bash
# Verify database is running
docker-compose ps db

# Test connection from backend
docker-compose exec backend python -c "from app.database import engine; print(engine.url)"

# Check credentials
docker-compose exec backend python -c "from app.database import SessionLocal; print('OK')"
```

### Scraping Failures

```bash
# Check Lucky California is accessible
curl -I https://www.luckyncal.com

# Verify Playwright browser installed
docker-compose exec backend python -c "from playwright.sync_api import sync_playwright; print('OK')"

# Manual retry
docker-compose exec backend python -c "from app.scraper.lucky_ca import LuckyCaliforniaScraper; s = LuckyCaliforniaScraper(); s.scrape_weekly_ad()"
```

### Email Not Sending

```bash
# Verify SendGrid API key
docker-compose exec backend python -c "import sendgrid; print('SendGrid imported')"

# Check SendGrid dashboard for failures
# Ensure sender email is verified in SendGrid
```

## Development

### Backend Development

```bash
# Enter backend container
docker-compose exec backend bash

# Run tests
pytest

# Run with hot reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### Frontend Development

```bash
# Enter frontend container
docker-compose exec frontend sh

# Run dev server with hot reload
npm run dev
```

### Database Migrations

```bash
# Create migration
alembic revision --autogenerate -m "add_new_table"

# Upgrade
alembic upgrade head

# Downgrade
alembic downgrade -1

# Show migration history
alembic history
```

## Health Checks

```bash
# Check backend health
curl http://localhost:8000/health

# Check database connectivity
curl http://localhost:8000/health/db

# Check all services
docker-compose ps
```

## Logs

### View All Logs

```bash
docker-compose logs -f
```

### View Specific Service

```bash
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f db
```

### Configure Log Level

In `backend/app/config.py`:
```python
LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR
```

## Security Notes

- Change default passwords in `.env`
- Use strong SSL certificates for production
- Consider VPN for remote database access
- Regularly update Docker images
- Review nginx access logs for suspicious activity

## Updating

```bash
# Pull latest code
git pull

# Rebuild images
docker-compose build

# Run migrations
docker-compose exec backend alembic upgrade head

# Restart services
docker-compose up -d
```

## Stopping Completely

```bash
docker-compose down        # Stop containers
docker-compose down -v     # Stop and remove volumes (DELETES DATA)
docker-compose down --rmi all  # Stop and remove images
```