docs: ajout dossier docs-bonne-pratiqueCI

Récap complet de l'infra CI sonic/openus : Gitea, Woodpecker server/agent, Dependency-Track, tips Woodpecker next, checklist nouvelle app. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-20 13:36:22 +01:00
parent 0aefbe012a
commit 4e02e59614
4 changed files with 734 additions and 0 deletions
--- a/docs-bonne-pratiqueCI/nouvelle-app-checklist.md
+++ b/docs-bonne-pratiqueCI/nouvelle-app-checklist.md
@@ -0,0 +1,304 @@
+# Checklist — Déployer une nouvelle app sur sonic
+
+Guide pas à pas pour passer d'un dépôt vide à une app déployée avec HTTPS, CI et SBOM.
+
+---
+
+## Prérequis (infra sonic, déjà en place)
+
+- [ ] sonic-fabio, sonic-consul, sonic-registrator, sonic-acme-1 actifs
+- [ ] Réseau Docker `sonic` existant : `docker network ls | grep sonic`
+- [ ] `/home/syoul/trivy-cache` existant (cache Trivy CVE)
+- [ ] Dependency-Track accessible sur `https://dtrack.syoul.fr`
+
+---
+
+## Étape 1 — Gitea
+
+- [ ] Créer le dépôt sur `git.open.us.org`
+- [ ] **Rendre le dépôt public** (Settings > Danger Zone > Visibility)
+  > Obligatoire : le token OAuth JWT Gitea est incompatible avec git clone HTTPS.
+  > Repo public = clone anonyme, aucun problème.
+- [ ] Initialiser avec `.gitignore` (ajouter `.env` et `/.reports/` minimum)
+
+---
+
+## Étape 2 — Woodpecker
+
+- [ ] Woodpecker UI > `+` > sélectionner le dépôt
+- [ ] Configurer les secrets (Settings > Secrets) :
+
+| Secret | Description |
+|---|---|
+| `app_domain` | Domaine de l'app (ex: `monapp.syoul.fr`) |
+| `db_password` | Mot de passe DB |
+| `db_root_password` | Mot de passe root DB |
+| *(autres secrets métier)* | … |
+| `dependency_track_token` | API key DTrack (peut être global si déjà configuré) |
+
+Générer des mots de passe forts :
+```bash
+openssl rand -base64 24
+```
+
+---
+
+## Étape 3 — DNS
+
+- [ ] Créer un enregistrement DNS `A` : `monapp.syoul.fr` → `161.97.174.60`
+- [ ] Vérifier la propagation : `dig +short monapp.syoul.fr` doit retourner `161.97.174.60`
+
+---
+
+## Étape 4 — `docker-compose.yml`
+
+Structure minimale avec les conventions sonic :
+
+```yaml
+name: ${COMPOSE_PROJECT_NAME:-syoul-monapp-main}
+
+services:
+  app:
+    image: mon-image:tag
+    container_name: ${COMPOSE_PROJECT_NAME:-syoul-monapp-main}-app
+    restart: always
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      # variables métier
+    volumes:
+      - app_data:/chemin/données
+    labels:
+      # Registrator enregistre dans Consul, Fabio route
+      - SERVICE_80_NAME=${SERVICE_80_NAME:-${COMPOSE_PROJECT_NAME}-app-80}
+      - SERVICE_80_TAGS=${SERVICE_80_TAGS:-urlprefix-${APP_DOMAIN}/*}
+      # HTTP check si service répond 2xx, TCP si redirection (301/302)
+      - SERVICE_80_CHECK_HTTP=/          # ou SERVICE_80_CHECK_TCP=true
+      - LETSENCRYPT_HOST=${APP_DOMAIN}   # info acme.sh (pas suffisant seul)
+    networks:
+      - app-net
+      - sonic
+
+  db:
+    image: mariadb:10.11   # ou postgres, etc.
+    container_name: ${COMPOSE_PROJECT_NAME:-syoul-monapp-main}-db
+    restart: always
+    environment:
+      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
+      MYSQL_DATABASE: monapp
+      MYSQL_USER: monapp
+      MYSQL_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - db_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    networks:
+      - app-net
+    # Pas de label SERVICE_* : DB non exposée publiquement
+
+volumes:
+  app_data:
+  db_data:
+
+networks:
+  app-net:
+    driver: bridge
+  sonic:
+    external: true
+```
+
+---
+
+## Étape 5 — `.woodpecker.yml`
+
+Structure type avec toutes les bonnes pratiques intégrées :
+
+```yaml
+when:
+  - branch: main
+    event: push
+
+steps:
+
+  - name: validate
+    image: docker:27-cli
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      DB_PASSWORD: placeholder
+      DB_ROOT_PASSWORD: placeholder
+      APP_DOMAIN: validate.example.com
+    commands:
+      - |
+        export COMPOSE_PROJECT_NAME=$(printf '%s-%s-%s' "$CI_REPO_OWNER" "$CI_REPO_NAME" "$CI_COMMIT_BRANCH" | tr 'A-Z/' 'a-z-')
+        docker compose config --quiet
+      - echo "docker-compose.yml valide"
+
+  - name: security-check
+    image: alpine:3.20
+    commands:
+      - |
+        if [ -f .env ]; then
+          echo "ERREUR: .env ne doit pas être commité"
+          exit 1
+        fi
+      - 'grep -q "^\.env$" .gitignore || (echo "ERREUR: .env manquant dans .gitignore" && exit 1)'
+      - echo "Security check OK"
+
+  # --- SBOM (optionnel, recommandé) ---
+  # Voir docs-sbom/integration-nouvelle-app.md pour le détail
+
+  - name: sbom-generate
+    image: alpine:3.20
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    commands:
+      - apk add --no-cache curl
+      - curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin latest
+      - mkdir -p .reports
+      - syft mon-image:tag -o cyclonedx-json --file .reports/sbom-app.cyclonedx.json
+      - syft mariadb:10.11 -o cyclonedx-json --file .reports/sbom-db.cyclonedx.json
+
+  - name: sbom-scan
+    image: aquasec/trivy:latest
+    volumes:
+      - /home/syoul/trivy-cache:/root/.cache/trivy
+    commands:
+      - trivy sbom --format json --output .reports/trivy-app.json .reports/sbom-app.cyclonedx.json
+      - trivy sbom --format json --output .reports/trivy-db.json .reports/sbom-db.cyclonedx.json
+
+  - name: sbom-publish
+    image: alpine/curl:latest
+    environment:
+      DTRACK_TOKEN:
+        from_secret: dependency_track_token
+    commands:
+      - |
+        VERSION=$(date +%Y-%m-%d)-$(echo "$CI_COMMIT_SHA" | cut -c1-8)
+        HTTP=$(curl -s -o /tmp/dtrack-resp.txt -w "%{http_code}" -X POST "https://dtrack.syoul.fr/api/v1/bom" \
+          -H "X-Api-Key: $DTRACK_TOKEN" \
+          -F "autoCreate=true" \
+          -F "projectName=monapp-app" \
+          -F "projectVersion=$VERSION" \
+          -F "bom=@.reports/sbom-app.cyclonedx.json")
+        echo "HTTP $HTTP : $(cat /tmp/dtrack-resp.txt)"
+        [ "$HTTP" -ge 200 ] && [ "$HTTP" -lt 300 ] || exit 1
+
+  # --- Déploiement ---
+
+  # NOTE: from_secret et volumes: incompatibles dans le même step (bug Woodpecker next)
+  - name: write-env
+    image: alpine:3.20
+    environment:
+      APP_DOMAIN:
+        from_secret: app_domain
+      DB_PASSWORD:
+        from_secret: db_password
+      DB_ROOT_PASSWORD:
+        from_secret: db_root_password
+    commands:
+      - env | grep -E "^(APP_DOMAIN|DB_PASSWORD|DB_ROOT_PASSWORD)=" > .env.deploy
+      - OWNER=$(echo "$CI_REPO_OWNER" | tr 'A-Z' 'a-z') && REPO=$(echo "$CI_REPO_NAME" | tr 'A-Z' 'a-z') && BRANCH=$(echo "$CI_COMMIT_BRANCH" | tr 'A-Z/' 'a-z-') && echo "COMPOSE_PROJECT_NAME=$OWNER-$REPO-$BRANCH" >> .env.deploy
+      - echo ".env.deploy créé ($(wc -c < .env.deploy) octets)"
+
+  - name: deploy
+    image: docker:27-cli
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /opt/monapp:/opt/monapp
+    commands:
+      - cp .env.deploy /opt/monapp/.env
+      - chmod 600 /opt/monapp/.env
+      - cp docker-compose.yml /opt/monapp/docker-compose.yml
+      - cd /opt/monapp && docker compose pull
+      - cd /opt/monapp && docker compose up -d --remove-orphans
+      - |
+        DOMAIN=$(grep '^APP_DOMAIN=' /opt/monapp/.env | cut -d= -f2)
+        PROJECT=$(grep '^COMPOSE_PROJECT_NAME=' /opt/monapp/.env | cut -d= -f2)
+        # Cert TLS (idempotent : exit 0 = émis, exit 2 = skip, autres = erreur)
+        ACME_EXIT=0
+        docker exec sonic-acme-1 /app/acme.sh \
+          --home /etc/acme.sh \
+          --issue -d "$DOMAIN" \
+          --webroot /usr/share/nginx/html \
+          --server letsencrypt \
+          --accountemail support+acme@asycn.io || ACME_EXIT=$?
+        [ "$ACME_EXIT" -ne 0 ] && [ "$ACME_EXIT" -ne 2 ] && exit 1
+        docker exec sonic-acme-1 cp /etc/acme.sh/$DOMAIN/fullchain.cer /host/certs/$DOMAIN-cert.pem
+        docker exec sonic-acme-1 cp /etc/acme.sh/$DOMAIN/$DOMAIN.key  /host/certs/$DOMAIN-key.pem
+        echo "TLS OK (acme exit $ACME_EXIT)"
+
+  - name: healthcheck
+    image: alpine:3.20
+    commands:
+      - apk add --no-cache --quiet curl
+      - |
+        SITE=$(grep '^APP_DOMAIN=' .env.deploy | cut -d= -f2)
+        TARGET="https://$SITE"
+        echo "Healthcheck $TARGET..."
+        MAX=60
+        i=0
+        until [ $i -ge $MAX ]; do
+          CODE=$(curl -sSo /dev/null -w "%{http_code}" "$TARGET" 2>/dev/null)
+          echo "Tentative $((i+1))/$MAX - HTTP $CODE"
+          if [ "$CODE" = "200" ] || [ "$CODE" = "301" ] || [ "$CODE" = "302" ]; then
+            echo "App répond sur $TARGET"
+            exit 0
+          fi
+          i=$((i+1))
+          sleep 10
+        done
+        echo "ERREUR: app ne répond pas après 10 minutes"
+        exit 1
+
+  - name: notify-failure
+    image: alpine:3.20
+    commands:
+      - 'echo "ECHEC pipeline #$CI_BUILD_NUMBER sur $CI_COMMIT_BRANCH ($CI_COMMIT_SHA)"'
+    when:
+      - status: failure
+```
+
+---
+
+## Étape 6 — Dossier de déploiement sur sonic
+
+Créer le dossier monté par le step `deploy` :
+
+```bash
+mkdir -p /opt/monapp
+```
+
+---
+
+## Étape 7 — Premier déploiement
+
+```bash
+git add .woodpecker.yml docker-compose.yml .gitignore
+git commit -m "feat: pipeline CI initiale"
+git push
+```
+
+Vérifications dans l'ordre :
+1. Woodpecker UI > pipeline en cours > tous les steps verts
+2. `docker ps | grep monapp` sur sonic → containers `up`
+3. `curl -Ik https://monapp.syoul.fr` → HTTP 200 ou 302
+4. `https://dtrack.syoul.fr` > Projects → projet `monapp-app` créé avec composants
+
+---
+
+## Récapitulatif des fichiers à créer
+
+```
+mon-repo/
+├── .woodpecker.yml       pipeline CI
+├── docker-compose.yml    stack Docker avec labels SERVICE_*
+├── .gitignore            .env et /.reports/ obligatoires
+└── .env.example          (optionnel) template des variables
+```
+
+Aucun fichier `.env` ne doit exister dans le dépôt. Tout passe par Woodpecker Secrets.