ciaovolo/flight-comparator/docs/DOCKER_README.md

Flight Radar Web App - Docker Quick Start

Get the entire application running in under 2 minutes! 🚀

---

One-Command Deployment

docker-compose up -d

Access the application:

• Frontend: http://localhost
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

---

What Gets Deployed?

Backend (Python FastAPI)

• RESTful API server
• SQLite database with schema
• Airport data (auto-downloaded)
• Rate limiting & logging
• Health checks

Frontend (React + Nginx)

• Production-optimized React build
• Nginx web server
• API proxy configuration
• Static asset caching
• Health checks

Networking

• Internal bridge network
• Backend accessible at backend:8000
• Frontend proxies API requests

---

Architecture

┌─────────────────────────────────────────────────┐
│  Docker Host                                    │
│                                                 │
│  ┌──────────────────┐      ┌─────────────────┐ │
│  │   Frontend       │      │    Backend      │ │
│  │   (nginx:80)     │◄────►│  (Python:8000)  │ │
│  │                  │      │                 │ │
│  │  - React App     │      │  - FastAPI      │ │
│  │  - Static Files  │      │  - SQLite DB    │ │
│  │  - API Proxy     │      │  - Rate Limit   │ │
│  └──────────────────┘      └─────────────────┘ │
│         │                         │             │
│         │                         │             │
│    Port 80                   Port 8000          │
└─────────┼─────────────────────────┼─────────────┘
          │                         │
          └─────────────────────────┘
            Host Machine Access

---

Quick Commands

Starting & Stopping

# Start (detached)
docker-compose up -d

# Start (with logs)
docker-compose up

# Stop
docker-compose down

# Restart
docker-compose restart

Monitoring

# View logs
docker-compose logs -f

# Check status
docker-compose ps

# Resource usage
docker stats flight-radar-backend flight-radar-frontend

Database

# Backup
docker cp flight-radar-backend:/app/cache.db ./backup.db

# Restore
docker cp ./backup.db flight-radar-backend:/app/cache.db

# Access database
docker-compose exec backend sqlite3 cache.db

Rebuilding

# Rebuild after code changes
docker-compose up --build

# Force rebuild
docker-compose build --no-cache

---

Ports

Service	Internal	External	Purpose
Frontend	80	80	Web UI
Backend	8000	8000	API Server

Change ports in .env:

FRONTEND_PORT=8080
BACKEND_PORT=8001

---

Volumes

Backend Data

• Volume: backend-data
• Mount: /app/data
• Contents: Database, cache files
• Persistence: Survives container restarts

Database File

• Mount: ./cache.db:/app/cache.db
• Type: Bind mount (optional)
• Purpose: Easy backup access

---

Environment Variables

Create .env from template:

cp .env.example .env

Key Variables:

# Backend
PORT=8000
ALLOWED_ORIGINS=http://localhost

# Rate Limits
RATE_LIMIT_SCANS=10
RATE_LIMIT_AIRPORTS=100

---

Health Checks

Both services have automatic health checks:

# Backend
curl http://localhost:8000/health

# Frontend
curl http://localhost/

# Docker health status
docker ps

Health indicators:

• healthy - Service operational
• starting - Initialization in progress
• unhealthy - Service down

---

Troubleshooting

Container won't start

# Check logs
docker-compose logs [service-name]

# Common issues:
# - Port already in use: Change port in .env
# - Build failed: Run docker-compose build --no-cache
# - Permission denied: Check file permissions

API not accessible from frontend

# Check nginx proxy config
docker-compose exec frontend cat /etc/nginx/conf.d/default.conf

# Test backend from frontend container
docker-compose exec frontend wget -qO- http://backend:8000/health

Database issues

# Reset database
docker-compose down
docker volume rm flight-comparator_backend-data
docker-compose up -d

---

Development Workflow

Code Changes

Backend changes:

# Edit Python files
# Rebuild and restart
docker-compose up --build backend

Frontend changes:

# Edit React files
# Rebuild and restart
docker-compose up --build frontend

Hot Reload (Development)

For development with hot reload, run services manually:

Backend:

python api_server.py

Frontend:

cd frontend
npm run dev

---

Production Deployment

Security Checklist

• Set ALLOWED_ORIGINS to production domain
• Use HTTPS (reverse proxy with SSL)
• Update rate limits for expected traffic
• Configure logging level to INFO or WARNING
• Set up automated backups
• Enable monitoring
• Review nginx security headers

Performance Optimization

# docker-compose.yml
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G

---

Useful Docker Commands

# Remove everything (reset)
docker-compose down -v

# View logs since 1 hour ago
docker-compose logs --since 1h

# Execute command in backend
docker-compose exec backend python --version

# Shell access
docker-compose exec backend bash
docker-compose exec frontend sh

# Copy files from container
docker cp flight-radar-backend:/app/cache.db ./

# Network inspection
docker network inspect flight-comparator_flight-radar-network

---

Files Created

• Dockerfile.backend - Backend container image
• Dockerfile.frontend - Frontend container image
• docker-compose.yml - Service orchestration
• nginx.conf - Nginx web server config
• .env.example - Environment template
• .dockerignore - Build optimization

---

Resource Requirements

Minimum:

• CPU: 1 core
• RAM: 2GB
• Disk: 5GB

Recommended:

• CPU: 2 cores
• RAM: 4GB
• Disk: 10GB

---

Next Steps

1. ✅ Start application: docker-compose up -d
2. ✅ Open browser: http://localhost
3. ✅ Create a scan
4. ✅ View results
5. ✅ Explore logs: http://localhost/logs

---

Need help? See DEPLOYMENT.md for detailed documentation.