docs: add server and CI/CD guides
This commit is contained in:
@@ -1,78 +1,129 @@
|
||||
---
|
||||
title: Déploiement avec Docker
|
||||
description: Construire les images, les publier puis les exécuter sur le serveur.
|
||||
title: Déployer avec Docker
|
||||
description: Livrer une image versionnée, vérifier sa santé et revenir en arrière.
|
||||
---
|
||||
|
||||
Une fois l'application dockerisée, le déploiement suit une chaîne simple :
|
||||
Le déploiement commence après la CI. Les tests ont réussi et une image immuable a été publiée dans un registry :
|
||||
|
||||
```text
|
||||
build des images
|
||||
↓
|
||||
push vers un registry
|
||||
↓
|
||||
image testée et versionnée
|
||||
↓
|
||||
pull sur le serveur
|
||||
↓
|
||||
docker compose up
|
||||
↓
|
||||
remplacement des conteneurs
|
||||
↓
|
||||
contrôles de santé
|
||||
```
|
||||
|
||||
Une CI/CD, par exemple GitHub Actions, automatise cette chaîne.
|
||||
<Callout title="Construire une fois, exécuter partout" type="success">
|
||||
Le serveur ne recompile rien. Il lance exactement l'image produite et validée par la CI.
|
||||
</Callout>
|
||||
|
||||
## CI : garder la branche saine
|
||||
|
||||
Sur chaque push vers la branche principale :
|
||||
|
||||
| Job | Contenu |
|
||||
| --- | --- |
|
||||
| `backend-checks` | lint, build, tests unitaires et tests e2e |
|
||||
| `frontend-checks` | lint, build et tests |
|
||||
| `build-images` | construction des images avec le fichier Compose de production |
|
||||
|
||||
Le job de build vérifie que les Dockerfiles continuent de produire des images valides.
|
||||
|
||||
## CD : publier une version
|
||||
|
||||
Lorsqu'un tag de version est poussé :
|
||||
|
||||
| Job | Contenu |
|
||||
| --- | --- |
|
||||
| Vérifications | Les mêmes contrôles que la CI |
|
||||
| `build-and-push` | Build des images et push vers Docker Hub, GHCR ou un autre registry |
|
||||
| `deploy` | Copie de la configuration puis connexion SSH au serveur |
|
||||
|
||||
## Build une fois, run partout
|
||||
|
||||
Le serveur ne recompile rien. Il récupère exactement l'image construite et testée par la CI :
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d --no-build
|
||||
docker image prune -f
|
||||
```
|
||||
|
||||
`--no-build` garantit que le serveur lance les images récupérées sans reconstruire depuis le code source.
|
||||
|
||||
## image et build dans le Compose de production
|
||||
## Préparer le Compose de production
|
||||
|
||||
```yaml
|
||||
services:
|
||||
backend:
|
||||
image: registry.example.com/mon-app/backend:${IMAGE_TAG:-latest}
|
||||
build:
|
||||
context: ./backend
|
||||
dockerfile: Dockerfile
|
||||
image: ghcr.io/organisation/mon-app-backend:${IMAGE_TAG:?IMAGE_TAG requis}
|
||||
restart: unless-stopped
|
||||
env_file:
|
||||
- .env.prod
|
||||
healthcheck:
|
||||
test:
|
||||
- CMD
|
||||
- node
|
||||
- -e
|
||||
- fetch('http://localhost:3000/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))
|
||||
interval: 10s
|
||||
timeout: 3s
|
||||
retries: 5
|
||||
start_period: 20s
|
||||
|
||||
postgres:
|
||||
image: postgres:16-alpine
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
```
|
||||
|
||||
Dans la CI, `build:` sert à construire puis pousser l'image. En production, le serveur utilise `image:` et `--no-build` pour exécuter le tag déjà publié.
|
||||
Le tag doit identifier une version précise, par exemple `v1.4.0` ou un SHA de commit. Évite `latest`, qui ne permet pas de savoir sans ambiguïté ce qui tourne.
|
||||
|
||||
Le serveur n'a besoin ni du code source, ni de Node.js, ni du toolchain de compilation. Il lui faut seulement Docker, le fichier Compose et un accès au registry.
|
||||
## Déployer une version
|
||||
|
||||
## Ce que Docker apporte
|
||||
Dans `/srv/mon-app`, écris le tag choisi dans `.env.release` :
|
||||
|
||||
- **Reproductibilité** : l'image testée par la CI est celle qui tourne en production.
|
||||
- **Rollback simple** : revenir en arrière revient à redéployer le tag précédent.
|
||||
- **Serveur minimal** : toutes les versions et dépendances vivent dans les images.
|
||||
- **Immutabilité** : on remplace une image complète au lieu de modifier le serveur en place.
|
||||
```dotenv
|
||||
IMAGE_TAG=v1.4.0
|
||||
```
|
||||
|
||||
<Callout title="Principe de livraison" type="success">
|
||||
Construis une fois et exécute partout. Une image versionnée est l'unité de livraison ; le tag identifie précisément la version déployée.
|
||||
Puis récupère et lance les images :
|
||||
|
||||
```bash
|
||||
docker compose \\
|
||||
--env-file .env.release \\
|
||||
-f docker-compose.prod.yml \\
|
||||
pull
|
||||
|
||||
docker compose \\
|
||||
--env-file .env.release \\
|
||||
-f docker-compose.prod.yml \\
|
||||
up -d --no-build --remove-orphans
|
||||
```
|
||||
|
||||
`--no-build` empêche toute reconstruction sur le serveur. Les données vivent dans les volumes et ne sont pas supprimées par le remplacement des conteneurs.
|
||||
|
||||
## Vérifier immédiatement
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.prod.yml ps
|
||||
docker compose -f docker-compose.prod.yml logs --tail=100
|
||||
curl --fail --show-error https://app.example.com/health
|
||||
```
|
||||
|
||||
Un déploiement n'est réussi que lorsque :
|
||||
|
||||
- les conteneurs sont démarrés et en bonne santé ;
|
||||
- les migrations de données ont terminé ;
|
||||
- l'URL publique répond ;
|
||||
- les journaux ne montrent pas de boucle d'erreurs ;
|
||||
- une action métier courte fonctionne.
|
||||
|
||||
## Revenir à la version précédente
|
||||
|
||||
Un rollback réutilise l'ancien tag :
|
||||
|
||||
```dotenv
|
||||
IMAGE_TAG=v1.3.2
|
||||
```
|
||||
|
||||
Relance ensuite `pull` puis `up -d --no-build`. Conserve au moins quelques versions dans le registry pour rendre ce retour possible.
|
||||
|
||||
<Callout title="Attention aux migrations" type="warn">
|
||||
Une image peut revenir en arrière, mais une migration destructive de base de données peut être irréversible. Préfère des migrations rétrocompatibles en plusieurs étapes et sauvegarde avant les changements sensibles.
|
||||
</Callout>
|
||||
|
||||
## Ce qui est déployé et ce qui persiste
|
||||
|
||||
| Élément | Comportement |
|
||||
| --- | --- |
|
||||
| image applicative | remplacée à chaque version |
|
||||
| conteneur | recréé à partir de l'image |
|
||||
| fichier Compose | versionné et copié explicitement |
|
||||
| secrets | conservés hors de Git sur le serveur ou dans un coffre |
|
||||
| volume de données | persiste entre les déploiements et doit être sauvegardé |
|
||||
| journaux | collectés et soumis à une rotation |
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] image versionnée disponible dans le registry ;
|
||||
- [ ] sauvegarde récente et restauration déjà testée ;
|
||||
- [ ] tag de la version précédente connu ;
|
||||
- [ ] configuration et secrets présents sur le serveur ;
|
||||
- [ ] healthchecks opérationnels ;
|
||||
- [ ] déploiement sérialisé pour éviter deux mises à jour simultanées ;
|
||||
- [ ] vérification fonctionnelle et rollback documentés.
|
||||
|
||||
La rubrique [CI/CD](/docs/ci-cd/principes) automatise maintenant ces étapes sans confondre validation, publication et mise en production.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"title": "Production",
|
||||
"description": "Livrer et exécuter les images",
|
||||
"title": "Déploiement",
|
||||
"description": "Livrer, vérifier et restaurer une version",
|
||||
"pages": ["deploiement"]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user