MACHINE VIRTUELLE                       CONTENEUR
  ┌───────────────────────────┐        ┌───────────────────────────┐
  │  App A    │    App B      │        │  App A    │    App B      │
  ├───────────┼───────────────┤        ├───────────┼───────────────┤
  │ Biblioth. │  Biblioth.    │        │ Biblioth. │  Biblioth.    │
  ├───────────┼───────────────┤        ├───────────┴───────────────┤
  │ Noyau OS  │  Noyau OS     │ ←──┐   │   moteur de conteneurs    │
  │  invité   │   invité      │    │   ├───────────────────────────┤
  ├───────────┴───────────────┤    │   │   NOYAU OS DE L'HÔTE      │ ← partagé
  │        Hyperviseur        │    │   ├───────────────────────────┤
  ├───────────────────────────┤    │   │        Matériel           │
  │      Noyau OS hôte        │    │   └───────────────────────────┘
  ├───────────────────────────┤    │
  │        Matériel           │    └── chaque VM embarque un système
  └───────────────────────────┘        d'exploitation complet

# lancer un conteneur (télécharge l'image si nécessaire)
docker run hello-world

# interactif : un shell dans un conteneur Python jetable
docker run -it --rm python:3.12-slim bash
#          │   └─ --rm : supprime le conteneur à la sortie (sinon il s'accumule)
#          └─ -it : mode interactif avec terminal

# en arrière-plan, avec un nom et une redirection de port
docker run -d --name mon-api -p 8000:8000 mon-image:1.0
#          │              └─ port 8000 de la MACHINE → port 8000 du CONTENEUR
#          └─ -d : detached, rend la main immédiatement

# voir ce qui tourne
docker ps                    # conteneurs en cours
docker ps -a                 # y compris ceux qui sont arrêtés
docker stats                 # consommation CPU / mémoire en direct

# lire les journaux
docker logs mon-api          # tout depuis le début
docker logs -f --tail 50 mon-api    # suivre en direct les 50 dernières lignes

# entrer dans un conteneur qui tourne (LE réflexe de débogage)
docker exec -it mon-api bash
docker exec mon-api python -c "import torch; print(torch.cuda.is_available())"

# inspecter en détail (configuration, réseaux, montages)
docker inspect mon-api
docker port mon-api          # quelles redirections de ports sont actives

# construire une image à partir du Dockerfile du répertoire courant
docker build -t mon-api:1.0 .
docker build -t mon-api:1.0 --build-arg VERSION=1.0 -f docker/Dockerfile .

# lister, étiqueter, publier
docker images
docker tag mon-api:1.0 ghcr.io/nils/mon-api:1.0
docker login ghcr.io && docker push ghcr.io/nils/mon-api:1.0
docker pull postgres:16

# arrêter et supprimer
docker stop mon-api && docker rm mon-api
docker rmi mon-api:1.0

# faire de la place (Docker consomme beaucoup de disque avec le temps)
docker system df             # ce qui occupe l'espace
docker container prune       # conteneurs arrêtés
docker image prune -a        # images non utilisées
docker system prune -a --volumes    # grand nettoyage — supprime aussi les VOLUMES

FROM python:3.12-slim      image de départ ("slim" = sans les outils de compilation)
WORKDIR /app               répertoire de travail ; le crée si besoin
COPY source destination    copie depuis la machine vers l'image
RUN commande               exécute PENDANT LA CONSTRUCTION (installer des paquets…)
ENV CLE=valeur             variable d'environnement, présente à l'exécution
ARG CLE=valeur             variable disponible seulement pendant la construction
EXPOSE 8000                documentation du port utilisé (ne publie rien par lui-même)
USER app                   change d'utilisateur : ne pas rester root
HEALTHCHECK …              commande que Docker lance pour vérifier la santé
CMD ["uvicorn", "…"]       commande lancée AU DÉMARRAGE du conteneur
ENTRYPOINT ["python"]      exécutable fixe ; CMD fournit alors ses arguments

# ════════ étape 1 : construire l'environnement ════════
FROM python:3.12-slim AS builder

# on récupère le binaire uv depuis son image officielle
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy

# ── couche STABLE : les dépendances ──
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev
#   --frozen : interdit de modifier le lock (échoue si désynchronisé)
#   --no-dev : pas de pytest/ruff dans l'image de production

# ── couche VOLATILE : le code ──
COPY src/ src/
RUN uv sync --frozen --no-dev

# ════════ étape 2 : image finale, sans outils de build ════════
FROM python:3.12-slim

WORKDIR /app
# on ne recopie que le résultat : l'environnement et le code
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/src /app/src
ENV PATH="/app/.venv/bin:$PATH"

# un utilisateur non privilégié : si l'application est compromise,
# l'attaquant n'est pas root dans le conteneur
RUN useradd --create-home app && chown -R app /app
USER app

EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

CMD ["uvicorn", "mon_projet.api:app", "--host", "0.0.0.0", "--port", "8000"]

.git
.venv
data/
notebooks/
models/
__pycache__/
*.parquet
*.csv
.pytest_cache
.ruff_cache

# VOLUME NOMMÉ : géré par Docker, stocké dans son espace. Pour les DONNÉES.
docker volume create donnees-pg
docker run -d --name pg -v donnees-pg:/var/lib/postgresql/data postgres:16
#                       └─ le volume survit à la suppression du conteneur

docker volume ls
docker volume inspect donnees-pg
docker volume rm donnees-pg          # là seulement, les données disparaissent

# BIND MOUNT : un dossier de la MACHINE est monté dans le conteneur.
# Pour le DÉVELOPPEMENT : le code modifié est visible immédiatement.
docker run -it --rm -v "$(pwd)":/app -w /app python:3.12-slim python script.py

# montage en lecture seule : un jeu de données que le conteneur ne doit pas modifier
docker run -v /data/brut:/data:ro mon-image

# créer un réseau : les conteneurs qui y sont attachés se voient PAR LEUR NOM
docker network create app-net

docker run -d --name base --network app-net postgres:16
docker run -d --name api  --network app-net -p 8000:8000 mon-api:1.0
# depuis "api", la base est joignable à l'adresse "base:5432" — Docker fournit
# une résolution DNS interne, il n'y a aucune adresse IP à connaître

# publier un port vers l'extérieur : -p HOTE:CONTENEUR
docker run -p 8080:8000 mon-api     # http://localhost:8080 → port 8000 du conteneur
docker run -p 127.0.0.1:8000:8000 mon-api   # accessible uniquement en local

docker network ls
docker network inspect app-net

docker run -e DATABASE_URL="postgresql://user:pass@base:5432/db" mon-api
docker run --env-file .env mon-api         # toutes les variables d'un fichier

# GPU (nécessite le NVIDIA Container Toolkit sur l'hôte)
docker run --gpus all nvidia/cuda:12.4.0-base nvidia-smi

services:

  api:
    build: .                        # construire depuis le Dockerfile local
    # image: ghcr.io/nils/mon-api:1.0   ← en production, on utilise une image publiée
    ports:
      - "8000:8000"                 # exposé sur la machine
    environment:
      DATABASE_URL: postgresql://app:${POSTGRES_PASSWORD}@base:5432/annonces
      REDIS_URL: redis://cache:6379/0
      LOG_LEVEL: info
    depends_on:
      base:
        condition: service_healthy  # attend que la base réponde VRAIMENT
      cache:
        condition: service_started
    volumes:
      - ./src:/app/src              # bind mount : rechargement à chaud en dev
    restart: unless-stopped         # redémarre en cas de crash, sauf arrêt manuel

  base:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}   # lu dans le fichier .env
      POSTGRES_DB: annonces
    volumes:
      - donnees-pg:/var/lib/postgresql/data     # LES DONNÉES SURVIVENT ICI
      - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro   # schéma au 1er démarrage
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d annonces"]
      interval: 5s
      timeout: 3s
      retries: 10
    # pas de "ports:" → la base n'est PAS exposée à l'extérieur, seulement à l'api

  cache:
    image: redis:7-alpine
    command: redis-server --save 60 1 --loglevel warning

volumes:
  donnees-pg:                       # volume nommé, géré par Docker

docker compose up -d              # démarre toute la pile en arrière-plan
docker compose up --build         # reconstruit les images avant de démarrer
docker compose ps                 # état des services
docker compose logs -f api        # suivre les journaux d'un service
docker compose exec api bash      # ouvrir un shell dans le service "api"
docker compose exec base psql -U app annonces      # un client SQL dans la base
docker compose restart api
docker compose stop               # arrête sans supprimer
docker compose down               # arrête ET supprime conteneurs + réseau
docker compose down -v            # … et SUPPRIME LES VOLUMES (donc les données)

docker compose run --rm api pytest         # lancer une commande ponctuelle
docker compose --profile dev up            # démarrer un sous-ensemble de services

PLAN DE CONTRÔLE (le cerveau)          NŒUDS DE TRAVAIL (les bras)
┌────────────────────────────┐         ┌──────────────┐  ┌──────────────┐
│ API server  ← tout passe   │         │   kubelet    │  │   kubelet    │
│              par lui       │◄───────►│      │       │  │      │       │
│ etcd        ← l'état       │         │   ┌──┴───┐   │  │   ┌──┴───┐   │
│              souhaité      │         │   │ Pod  │   │  │   │ Pod  │   │
│ scheduler   ← place les    │         │   │ Pod  │   │  │   │ Pod  │   │
│              pods          │         │   └──────┘   │  │   └──────┘   │
│ controllers ← corrigent    │         │ kube-proxy   │  │ kube-proxy   │
│              les écarts    │         └──────────────┘  └──────────────┘
└────────────────────────────┘

apiVersion: apps/v1
kind: Deployment
metadata:
  name: model-api
  labels: { app: model-api }
spec:
  replicas: 3                          # trois exemplaires en permanence
  selector:
    matchLabels: { app: model-api }    # quels pods ce Deployment gère-t-il
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1                      # au plus 1 pod en trop pendant la mise à jour
      maxUnavailable: 0                # aucun pod indisponible : zéro coupure
  template:                            # ── le modèle de pod à créer ──
    metadata:
      labels: { app: model-api }       # doit correspondre au selector ci-dessus
    spec:
      containers:
        - name: api
          image: ghcr.io/nils/model-api:1.4.2    # JAMAIS :latest en production
          ports:
            - containerPort: 8000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef: { name: db-credentials, key: url }
          resources:
            requests:                  # RÉSERVÉ : sert au scheduler pour le placement
              cpu: "500m"              # 500 millicœurs = 0,5 cœur
              memory: "1Gi"
            limits:                    # PLAFOND : au-delà, le conteneur est bridé (CPU)
              cpu: "2"                 #           ou tué (mémoire : OOMKilled)
              memory: "4Gi"
              nvidia.com/gpu: 1        # un GPU entier (non partageable par défaut)
          readinessProbe:              # "puis-je recevoir du trafic ?"
            httpGet: { path: /health, port: 8000 }
            initialDelaySeconds: 20    # laisse le temps de charger le modèle
            periodSeconds: 10
          livenessProbe:               # "suis-je encore vivant ?" sinon → redémarrage
            httpGet: { path: /health, port: 8000 }
            initialDelaySeconds: 60
            periodSeconds: 30
---
apiVersion: v1
kind: Service                          # l'adresse stable devant les 3 pods
metadata:
  name: model-api
spec:
  selector: { app: model-api }         # sélectionne les pods par leur étiquette
  ports:
    - port: 80                         # port du Service
      targetPort: 8000                 # port du conteneur
  type: ClusterIP

kubectl apply -f deployment.yaml      # applique l'état souhaité (créé ou mis à jour)
kubectl get pods                      # lister ; -w pour suivre en direct
kubectl get all -n mon-namespace
kubectl describe pod model-api-7d9f   # événements : LA commande de diagnostic
kubectl logs -f model-api-7d9f        # journaux ; --previous après un crash
kubectl exec -it model-api-7d9f -- bash
kubectl port-forward svc/model-api 8080:80    # tester en local sans exposer

kubectl rollout status deploy/model-api       # suivre une mise à jour
kubectl rollout undo deploy/model-api         # RETOUR ARRIÈRE immédiat
kubectl scale deploy/model-api --replicas=5
kubectl top pods                              # consommation réelle
kubectl delete -f deployment.yaml