school_compare/DOCKER_DEPLOY.md

# Docker Deployment Guide

## Quick Start

Deploy the complete SchoolCompare stack (PostgreSQL + FastAPI + Next.js) with one command:

```bash
docker-compose up -d
```

This will start:
- **PostgreSQL** on port 5432 (database)
- **FastAPI** on port 8000 (backend API)
- **Next.js** on port 3000 (frontend)

## Service Details

### PostgreSQL Database
- **Port**: 5432
- **Container**: `schoolcompare_db`
- **Credentials**:
  - User: `schoolcompare`
  - Password: `schoolcompare`
  - Database: `schoolcompare`
- **Volume**: `postgres_data` (persistent storage)

### FastAPI Backend
- **Port**: 8000 → 80 (container)
- **Container**: `schoolcompare_backend`
- **Built from**: Root `Dockerfile`
- **API Endpoint**: http://localhost:8000/api
- **Health Check**: http://localhost:8000/api/data-info

### Next.js Frontend
- **Port**: 3000
- **Container**: `schoolcompare_nextjs`
- **Built from**: `nextjs-app/Dockerfile`
- **URL**: http://localhost:3000
- **Connects to**: Backend via internal network

## Commands

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

### View logs
```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f nextjs
docker-compose logs -f backend
docker-compose logs -f db
```

### Check status
```bash
docker-compose ps
```

### Stop all services
```bash
docker-compose down
```

### Rebuild after code changes
```bash
# Rebuild and restart specific service
docker-compose up -d --build nextjs

# Rebuild all services
docker-compose up -d --build
```

### Clean restart (remove volumes)
```bash
docker-compose down -v
docker-compose up -d
```

## Initial Database Setup

After first start, you may need to initialize the database:

```bash
# Enter the backend container
docker exec -it schoolcompare_backend bash

# Run migrations or data loading
python -m backend.data_loader
```

## Accessing Services

Once running:
- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000/api
- **API Docs**: http://localhost:8000/docs (Swagger UI)
- **Database**: localhost:5432 (use any PostgreSQL client)

## Environment Variables

Create a `.env` file in the root directory to customize:

```env
# Database
POSTGRES_USER=schoolcompare
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=schoolcompare

# Backend
DATABASE_URL=postgresql://schoolcompare:your_secure_password@db:5432/schoolcompare

# Frontend (for client-side access)
NEXT_PUBLIC_API_URL=http://localhost:8000/api
```

Then run:
```bash
docker-compose up -d
```

## Troubleshooting

### Backend not connecting to database
```bash
# Check database health
docker-compose ps

# View backend logs
docker-compose logs backend

# Restart backend
docker-compose restart backend
```

### Frontend not connecting to backend
```bash
# Check backend health
curl http://localhost:8000/api/data-info

# Check Next.js environment variables
docker exec schoolcompare_nextjs env | grep API
```

### Port already in use
```bash
# Change ports in docker-compose.yml
# For example, change "3000:3000" to "3001:3000"
```

### Rebuild from scratch
```bash
docker-compose down -v
docker system prune -a
docker-compose up -d --build
```

## Production Deployment

For production, update the following:

1. **Use secure passwords** in `.env` file
2. **Configure reverse proxy** (Nginx) in front of Next.js
3. **Enable HTTPS** with SSL certificates
4. **Set production environment variables**:
   ```env
   NODE_ENV=production
   POSTGRES_PASSWORD=<strong-password>
   ```
5. **Backup database** regularly:
   ```bash
   docker exec schoolcompare_db pg_dump -U schoolcompare schoolcompare > backup.sql
   ```

## Network Architecture

```
Internet
    ↓
Next.js (port 3000) ← User browsers
    ↓ (internal network)
FastAPI (port 8000) ← API calls
    ↓ (internal network)
PostgreSQL (port 5432) ← Data queries
```

All services communicate via the `schoolcompare-network` Docker network.