docker-compose.yml

services:

  # 🧠 THE ENGINE(S): FastAPI services

  # 🧠 Service v1
  # NOTE: We scale with `docker compose ... --scale api-v1=3` (works with normal Docker Compose) instead of `deploy.replicas`.
  # `deploy.replicas` comes from Docker Swarm mode (Docker’s built-in cluster/orchestrator). In plain Compose it may be ignored
  # (or behave inconsistently), so `--scale` is the safest/most portable way for this setup.
  api-v1:
    build:
      context: .
      dockerfile: src/api/v1/Dockerfile 
    # Internal-only: reachable from other services (e.g., Nginx) on the Docker network.
    # Not published to the host -> allows scaling multiple replicas without host-port conflicts.  
    expose:  
      - "8000" 

  # 🧠 Service v2
  api-v2:
    build:
      context: .
      dockerfile: src/api/v2/Dockerfile 
    # Internal-only: reachable from other services (e.g., Nginx) on the Docker network.
    # Not published to the host -> allows scaling multiple replicas without host-port conflicts.  
    expose:  
      - "8000" 

  # 🛡️ THE GATEKEEPER: Nginx Reverse Proxy  (single entrypoint)
  nginx:
    build:
      context: deployments/nginx/
      dockerfile: Dockerfile
    # Publish container ports to the host:
    # - 8080 on the host forwards to Nginx port 80 in the container (HTTP, redirect-only)
    # - 443 on the host forwards to Nginx port 443 in the container (HTTPS entrypoint)    
    ports:
      - "8080:80"  # HTTP (used only to redirect -> HTTPS)
      - "443:443"  # HTTPS (Port 443 - standard TLS port) for secure communication
    volumes:
      # Bind-mount repo files/folders INTO the container so Nginx can read them, 
      #
      # But: The files are NOT copied into the image (i.e. this is not the same then 
      # the COPY-Command in dockerfiles which build time (docker build):
      # Instead, with bind-mount, Nginx reads the following files directly from the hosts's 
      # filesystem at runtime (docker compose up) which OVERRIDES anything we may have COPY'd 
      # in the Dockerfile at the same path. The nginx-container can see aby change on those files
      # on the host immediately. 
      # This is useful for fast iteration (edit file -> restart/reload Nginx, no need to rebuild).
      #
      # Syntax: host_path : container_path
      # :ro = read-only (container cannot modify your repo files)
      #
      #
      # nginx.conf -> main config file that Nginx loads on startup
      - ./deployments/nginx/nginx.conf:/etc/nginx/nginx.conf:ro

      # certs/ -> provides nginx.crt + nginx.key at the exact paths used in nginx.conf
      - ./deployments/nginx/certs:/etc/nginx/certs:ro

      # .htpasswd -> credential hash file used by auth_basic_user_file in nginx.conf
      - ./deployments/nginx/.htpasswd:/etc/nginx/.htpasswd:ro
    depends_on:
      - api-v1
      - api-v2

  # 📊 THE TRANSLATOR: Scrapes Nginx stats and converts them to Prometheus format
  # The exporter pulls from Nginx, then exposes Prometheus metrics on :9113/metrics.
  nginx_exporter:
    image: nginx/nginx-prometheus-exporter:latest
    # Optional: expose exporter metrics to the host for quick sanity checks
    # (Prometheus itself scrapes it internally via the Compose network)
    ports:
      - "9113:9113" # expose exporter to host for quick checking
    depends_on:
      - nginx
    # Tell the exporter where to fetch Nginx stub_status from.
    # We scrape INTERNAL HTTP on nginx:8081 to avoid:
    # - port 80 redirecting to HTTPS
    # - self-signed cert validation issues on port 443      
    command:
      - "--nginx.scrape-uri=http://nginx:8081/nginx_status"

  prometheus:
    image: prom/prometheus:latest
    # container_name: prometheus_server
    ports:
      - "9090:9090"
    volumes:
      - ./deployments/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus_data:/prometheus
    depends_on:
      - nginx

  grafana:
    image: grafana/grafana:latest
    # container_name: grafana_dashboard
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    depends_on:
      - prometheus
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin

# Define named Docker volumes managed by Docker (not the host filesystem).
#
# - prometheus_data: persists Prometheus time-series DB across restarts
# - grafana_data: persists Grafana settings/dashboards/users across restarts
#
# Without these, we’d lose data on docker compose down (depending on flags) or container recreation.
volumes:
  prometheus_data:
  grafana_data: