Docker Guide

🐳 Docker Guide

---

Services

Container	Image	Port	Description
airsafenet_frontend	Nginx + React	5173	Web dashboard
airsafenet_backend	ASP.NET Core 8	7276	REST API
airsafenet_ai	Python 3.11 + FastAPI	8000	AI inference
airsafenet_db	PostgreSQL 16	Internal	Database

---

Compose Files

File	Purpose
docker-compose.yml	Base config (always used)
docker-compose.override.yml	Dev: hot reload, DB port exposed
docker-compose.prod.yml	Prod: registry images, resource limits

---

Common Commands

# ── Development ──────────────────────────────────────
# Start with hot reload (auto-loads override.yml)
docker compose up -d

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

# View logs in real time
docker compose logs -f ai_server
docker compose logs -f backend

# ── Production ───────────────────────────────────────
# Use registry images
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# ── Maintenance ──────────────────────────────────────
# Stop containers (keep volumes)
docker compose down

# Stop + delete all data
docker compose down -v

# Restart single service
docker compose restart backend

# Open shell in container
docker compose exec ai_server bash
docker compose exec backend bash

---

Persistent Volumes

Volume	Mount Point	Contents
postgres_data	/var/lib/postgresql/data	All database data
ai_data	/app/data	Cache CSV/JSON files
ai_models	/app/models	Trained model .pkl files
backend_data	/app/data	Backend file storage

---

Development Override

docker-compose.override.yml activates automatically in dev:

• Frontend: Vite dev server with hot reload on port 5173
• Backend: dotnet watch — restarts on file changes
• AI Server: uvicorn --reload — restarts on file changes
• Database: port 5432 exposed for pgAdmin / DBeaver

---

Placing Model File

The AI server downloads the model from HuggingFace on first start via entrypoint.sh:

MODEL_URL="https://huggingface.co/nguyentribaothang/airsafenet/resolve/main/airsafenet_best_model.pkl"

Or place manually:

# Copy model into the running container
docker compose cp your_model.pkl ai_server:/app/models/airsafenet_best_model.pkl

# Or into the named volume directly
docker run --rm -v airsafenet_ai_models:/models \
  -v $(pwd):/host alpine cp /host/model.pkl /models/airsafenet_best_model.pkl

---

Troubleshooting

AI Server not starting:

docker compose logs ai_server
# Common causes:
# - model.pkl not found → check entrypoint.sh download or place manually
# - import error → run_compute fails on first start

Backend can't connect to DB:

docker compose logs db
# Wait for: "database system is ready to accept connections"
docker compose restart backend

Frontend blank page:

# Check VITE_API_BASE_URL in .env points to backend
docker compose logs frontend

Recompute not working:

# Trigger manually
curl -X POST http://localhost:8000/admin/compute \
  -H "X-Admin-Key: $(grep ADMIN_KEY .env | cut -d= -f2)"