Spaces:
Running
Running
| # ============================================================================ | |
| # MULTI-STAGE DOCKERFILE: Development + Production | |
| # ============================================================================ | |
| # What is multi-stage build? | |
| # - ONE Dockerfile that can create DIFFERENT images for dev vs prod | |
| # - Uses "FROM ... AS stage-name" to define stages | |
| # - Build specific stage with: `docker build --target stage-name -t image:tag .` | |
| # | |
| # Benefits: | |
| # - Single source of truth (one Dockerfile, not two separate files) | |
| # - Share common setup (base stage) between dev and prod | |
| # - Actually different images (not just different docker-compose configs) | |
| # | |
| # Reference: docker_images_vs_services.md - Approach B (Multi-Stage Dockerfile) | |
| # ============================================================================ | |
| # ============================================================================ | |
| # STAGE 1: BASE (Shared by both dev and prod) | |
| # ============================================================================ | |
| # Why separate base stage? | |
| # - Avoid duplicating common setup (Python install, uv setup, dependencies) | |
| # - Changes here affect both dev and prod | |
| # - Faster builds (shared layers cached once) | |
| # ============================================================================ | |
| FROM python:3.11-slim AS base | |
| # Set working directory to project root | |
| # NOTE: Changed from /app to /project to support absolute imports (app.*) | |
| # This allows imports like "from app.utils.config import get_logger" | |
| # to work consistently in both IDE and Docker environments | |
| WORKDIR /project | |
| # Install uv (modern Python package manager) | |
| # COPY --from=IMAGE means: copy FROM another image (not from host) | |
| # Source: /uv (binary from astral-sh's image) | |
| # Destination: /usr/local/bin/uv (system PATH in our image) | |
| # Why uv? Faster than pip, uses lockfile (uv.lock) for reproducible builds | |
| COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv | |
| # Copy dependency files first (for layer caching optimization) | |
| # Why before code? Dependencies change less frequently than code | |
| # If only code changes, Docker reuses this cached layer (faster rebuilds) | |
| # | |
| # What are these files? | |
| # - pyproject.toml = Python project metadata + dependency list (like package.json) | |
| # - uv.lock = Exact pinned versions of all dependencies (like package-lock.json) | |
| COPY pyproject.toml uv.lock ./ | |
| # Install dependencies using uv | |
| # Using "uv pip install" instead of "uv sync" for system-wide installation | |
| # | |
| # Flags explained: | |
| # pip install = Use pip-compatible interface (supports --system) | |
| # --system = Install to system Python (not venv) - CRITICAL for Docker | |
| # -r pyproject.toml = Install from project dependencies | |
| # | |
| # Why --system is required in Docker: | |
| # | |
| # WITHOUT --system (default behavior): | |
| # - uv creates a virtual environment (.venv/) and installs packages there | |
| # - Executables end up in: .venv/bin/uvicorn (hidden location) | |
| # - Docker can't find them in PATH → Error: "No such file or directory" | |
| # - You'd need to use "uv run uvicorn ..." which adds complexity | |
| # | |
| # WITH --system: | |
| # - uv installs directly to system Python (no .venv/ folder created) | |
| # - Executables go to: /usr/local/bin/uvicorn (standard PATH location) | |
| # - Docker finds them immediately → uvicorn command just works | |
| # - Cleaner CMD: just "uvicorn ..." instead of "uv run uvicorn ..." | |
| # | |
| # Why virtual environments (.venv/) are "extra" in Docker: | |
| # On your laptop: .venv/ needed to separate multiple projects | |
| # - Project A needs pandas 1.0 | |
| # - Project B needs pandas 2.0 | |
| # - .venv/ prevents conflicts | |
| # | |
| # In Docker: Container itself provides isolation | |
| # - Container 1 has its own Python + packages (completely isolated) | |
| # - Container 2 has its own Python + packages (can't see Container 1) | |
| # - .venv/ inside container = locking a safe inside another safe (redundant) | |
| # | |
| # Analogy: | |
| # Without --system = Hiding keys in a drawer (Docker can't find them) | |
| # With --system = Putting keys on the key hook (Docker finds them easily) | |
| # | |
| # This replaces traditional: pip install -r requirements.txt | |
| RUN uv pip install --system -r pyproject.toml | |
| # Copy application code | |
| # NOTE: Changed to copy entire project instead of just app/ directory | |
| # This maintains the project structure: /project/app/, /project/pyproject.toml, etc. | |
| # Allows absolute imports like "from app.utils.config import get_logger" to work | |
| # | |
| # Source: ./ (entire project root on host) | |
| # Destination: . (current WORKDIR, which is /project inside container) | |
| # | |
| # Result: Files land at /project/app/main.py, /project/app/models/, etc. | |
| COPY . . | |
| # ============================================================================ | |
| # Why we DON'T set CMD or ENV here? | |
| # - Base stage is INCOMPLETE - not meant to run directly | |
| # - Each final stage (development/production) will set their own CMD and ENV | |
| # - This keeps base stage flexible for different use cases | |
| # ============================================================================ | |
| # ============================================================================ | |
| # STAGE 2: DEVELOPMENT | |
| # ============================================================================ | |
| # When to use this stage? | |
| # - Local development on host machine | |
| # - Need hot reload (code changes auto-restart server) | |
| # - Need debug mode (verbose logging, error traces) | |
| # - Don't care about image size or optimization | |
| # | |
| # How to build: docker build --target development -t smart-chatbot:dev . | |
| # ============================================================================ | |
| FROM base AS development | |
| # Set environment variables for development | |
| # DEBUG=true enables: | |
| # - Verbose logging | |
| # - Detailed error traces in API responses | |
| # - Development-only features | |
| ENV DEBUG=true | |
| # Development-specific command | |
| # Flags explained: | |
| # uvicorn = ASGI server for FastAPI (installed to system with --system flag) | |
| # app.main:app = Import path (app/main.py file, app object) - using absolute import | |
| # --reload = Watch for code changes, auto-restart server (hot reload) | |
| # --host 0.0.0.0 = Listen on ALL network interfaces (required for Docker) | |
| # --port 8000 = Port number (matches EXPOSE, nginx proxy_pass target) | |
| # | |
| # NOTE: Changed from "main:app" to "app.main:app" to match absolute import structure | |
| # This works because WORKDIR is /project (contains app/ directory) | |
| # | |
| # Why different from production CMD? | |
| # - --reload is EXPENSIVE (file watching, auto-restart) - only for development | |
| # - Production uses gunicorn (multi-worker, more robust) | |
| # | |
| # Note: No "uv run" needed because we used --system flag during install | |
| CMD ["uvicorn", "app.main:app", "--reload", "--host", "0.0.0.0", "--port", "8000"] | |
| # Port documentation (doesn't actually open ports) | |
| # How this works with docker-compose in DEVELOPMENT: | |
| # | |
| # smart-chatbot: | |
| # image: smart-chatbot:dev | |
| # ports: | |
| # - "8000:8000" ← EXPOSED to host | |
| # volumes: | |
| # - ./app:/app ← Bind mount (code changes reflect immediately) | |
| # | |
| # Access options: | |
| # - Direct: http://localhost:8000 | |
| # - Via nginx proxy: http://smart-chatbot.local (requires /etc/hosts + nginx config) | |
| EXPOSE 8000 | |
| # ============================================================================ | |
| # STAGE 3: PRODUCTION | |
| # ============================================================================ | |
| # When to use this stage? | |
| # - Deploying to server (Railway, AWS, DigitalOcean, etc.) | |
| # - Need performance (multi-worker, optimized) | |
| # - Need security (debug off, minimal attack surface) | |
| # - Care about image size and resource usage | |
| # | |
| # How to build: docker build --target production -t smart-chatbot:prod . | |
| # ============================================================================ | |
| FROM base AS production | |
| # Set environment variables for production | |
| # DEBUG=false disables: | |
| # - Verbose logging (only errors/warnings logged) | |
| # - Detailed error traces (attackers can't see internal structure) | |
| # - Development-only features | |
| ENV DEBUG=false | |
| # Production-specific command | |
| # Why gunicorn instead of uvicorn? | |
| # - Gunicorn = Production-grade WSGI server with process management | |
| # - Can run MULTIPLE workers (parallel request handling) | |
| # - Better stability, graceful shutdowns, worker health monitoring | |
| # | |
| # Flags explained: | |
| # gunicorn = WSGI server (wraps uvicorn workers, installed to system) | |
| # app.main:app = Import path (app/main.py file, app object) - using absolute import | |
| # -k uvicorn.workers.UvicornWorker = Use Uvicorn worker class (for ASGI support) | |
| # -w 4 = 4 worker processes (adjust based on CPU cores) | |
| # -b 0.0.0.0:8000 = Bind to all interfaces, port 8000 | |
| # | |
| # NOTE: Changed from "main:app" to "app.main:app" to match absolute import structure | |
| # This works because WORKDIR is /project (contains app/ directory) | |
| # | |
| # Worker count rule of thumb: (2 × CPU_cores) + 1 | |
| # Example: 2-core server → 5 workers, 4-core server → 9 workers | |
| # | |
| # Note: No "uv run" needed because we used --system flag during install | |
| CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", "-w", "4", "-b", "0.0.0.0:8000"] | |
| # Port documentation (doesn't actually open ports) | |
| # How this works with docker-compose in PRODUCTION: | |
| # | |
| # smart-chatbot: | |
| # image: smart-chatbot:prod | |
| # expose: | |
| # - 8000 ← INTERNAL ONLY (only other containers can access) | |
| # # NO "ports:" section = NOT accessible from host/internet | |
| # | |
| # nginx: | |
| # ports: | |
| # - "80:80" ← Only nginx exposed to internet | |
| # # nginx.conf: proxy_pass http://smart-chatbot:8000 | |
| # | |
| # Request flow: Internet → nginx:80 → smart-chatbot:8000 (internal) | |
| EXPOSE 8000 | |
| # ============================================================================ | |
| # STAGE 4: HUGGINGFACE SPACE | |
| # ============================================================================ | |
| FROM base AS huggingface | |
| ENV DEBUG=false | |
| ENV ENVIRONMENT=production | |
| # HuggingFace Spaces default port is 7860 | |
| CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"] | |
| EXPOSE 7860 | |
| # ============================================================================ | |
| # HOW TO USE THIS DOCKERFILE | |
| # ============================================================================ | |
| # | |
| # BUILD DEVELOPMENT IMAGE: | |
| # docker build --target development -t smart-chatbot:dev . | |
| # | |
| # BUILD PRODUCTION IMAGE: | |
| # docker build --target production -t smart-chatbot:prod . | |
| # | |
| # BUILD BOTH (for testing): | |
| # docker build --target development -t smart-chatbot:dev . | |
| # docker build --target production -t smart-chatbot:prod . | |
| # | |
| # VERIFY IMAGES EXIST: | |
| # docker images | grep smart-chatbot | |
| # | |
| # RUN DEVELOPMENT CONTAINER (standalone, no compose): | |
| # docker run -p 8000:8000 -v $(pwd)/app:/app smart-chatbot:dev | |
| # | |
| # RUN PRODUCTION CONTAINER (standalone, no compose): | |
| # docker run -p 8000:8000 smart-chatbot:prod | |
| # | |
| # ============================================================================ | |
| # WHAT'S THE DIFFERENCE BETWEEN IMAGES? | |
| # ============================================================================ | |
| # | |
| # smart-chatbot:dev (DEVELOPMENT) | |
| # ✅ Has: --reload flag (hot reload for code changes) | |
| # ✅ Has: DEBUG=true (verbose logging, error traces) | |
| # ✅ Has: Single-worker uvicorn (simpler debugging) | |
| # ❌ Slower, higher memory usage, less secure | |
| # | |
| # smart-chatbot:prod (PRODUCTION) | |
| # ✅ Has: Multi-worker gunicorn (parallel requests, better performance) | |
| # ✅ Has: DEBUG=false (minimal logging, no error traces) | |
| # ✅ Has: Optimized for speed and security | |
| # ❌ No hot reload (must rebuild image for code changes) | |
| # | |
| # ============================================================================ | |
| # WHAT ABOUT DOCKER-COMPOSE? | |
| # ============================================================================ | |
| # You can use these images in docker-compose.yml: | |
| # | |
| # DEVELOPMENT (docker-compose.dev.yml): | |
| # services: | |
| # smart-chatbot: | |
| # image: smart-chatbot:dev ← Uses development stage | |
| # ports: | |
| # - "8000:8000" ← Exposed to host (localhost:8000) | |
| # volumes: | |
| # - ./app:/app ← Bind mount (hot reload works!) | |
| # | |
| # PRODUCTION (docker-compose.prod.yml): | |
| # services: | |
| # smart-chatbot: | |
| # image: smart-chatbot:prod ← Uses production stage | |
| # expose: | |
| # - 8000 ← Internal only (nginx access only) | |
| # # NO volumes (code baked into image) | |
| # | |
| # nginx: | |
| # image: nginx:alpine | |
| # ports: | |
| # - "80:80" ← Only nginx exposed to internet | |
| # | |
| # ============================================================================ | |