school_compare/DOCKER_DEPLOY.md

Docker Deployment Guide

Quick Start

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

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

docker-compose up -d

View logs

# 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

docker-compose ps

Stop all services

docker-compose down

Rebuild after code changes

# Rebuild and restart specific service
docker-compose up -d --build nextjs

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

Clean restart (remove volumes)

docker-compose down -v
docker-compose up -d

Initial Database Setup

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

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

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

docker-compose up -d

Troubleshooting

Backend not connecting to database

# Check database health
docker-compose ps

# View backend logs
docker-compose logs backend

# Restart backend
docker-compose restart backend

Frontend not connecting to backend

# 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

# Change ports in docker-compose.yml
# For example, change "3000:3000" to "3001:3000"

Rebuild from scratch

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:

   NODE_ENV=production
   POSTGRES_PASSWORD=<strong-password>
   

5. Backup database regularly:

   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.