453 lines
8.9 KiB
Markdown
453 lines
8.9 KiB
Markdown
# 🐳 Déploiement Docker - Notytex v2
|
|
|
|
Guide complet pour déployer Notytex avec Docker et Docker Compose.
|
|
|
|
---
|
|
|
|
## 🚀 Démarrage Rapide
|
|
|
|
### Prérequis
|
|
|
|
- **Docker** : 24.0+ (ou Docker Desktop 4.20+)
|
|
- **Docker Compose** : 2.20+
|
|
- **Alternative Podman** : Podman 4.0+ avec podman-compose
|
|
|
|
### Installation en 3 commandes
|
|
|
|
```bash
|
|
# 1. Configurer l'environnement
|
|
cd docker
|
|
cp .env.example .env
|
|
# Éditez .env et changez SECRET_KEY !
|
|
|
|
# 2. Créer le répertoire de données (si nécessaire)
|
|
mkdir -p ../data
|
|
|
|
# 3. Démarrer les services
|
|
docker compose up -d
|
|
```
|
|
|
|
**Accès :**
|
|
- Frontend : http://localhost:8081
|
|
- API Backend : http://localhost:8080
|
|
- Documentation API : http://localhost:8080/api/v2/docs
|
|
|
|
---
|
|
|
|
## 📂 Organisation des Fichiers
|
|
|
|
```
|
|
docker/
|
|
├── compose.yaml # Configuration PRODUCTION (défaut)
|
|
├── compose.override.yaml # Override DÉVELOPPEMENT (auto-merge)
|
|
├── .env.example # Template de variables d'environnement
|
|
└── README.md # Ce fichier
|
|
|
|
../backend/
|
|
├── Dockerfile # Image backend FastAPI
|
|
└── ...
|
|
|
|
../frontend/
|
|
├── Dockerfile # Image frontend Vue.js + Nginx
|
|
└── ...
|
|
|
|
../data/ # Volume persistant (base de données SQLite)
|
|
└── school_management.db
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Variables d'Environnement
|
|
|
|
Copiez `.env.example` vers `.env` et personnalisez :
|
|
|
|
```bash
|
|
# Clé secrète (OBLIGATOIRE - générez-en une nouvelle !)
|
|
SECRET_KEY=votre-cle-secrete-unique-min-32-chars
|
|
|
|
# Configuration du registre Docker (pour production avec images pré-buildées)
|
|
REGISTRY_URL=docker.io
|
|
REGISTRY_NAMESPACE=notytex
|
|
IMAGE_TAG=latest
|
|
|
|
# Ports exposés
|
|
BACKEND_PORT=8080
|
|
FRONTEND_PORT=8081
|
|
|
|
# CORS (ajoutez vos domaines en production)
|
|
CORS_ORIGINS=["http://localhost:8081","https://votre-domaine.com"]
|
|
```
|
|
|
|
### Générer une SECRET_KEY
|
|
|
|
```bash
|
|
python -c "import secrets; print(secrets.token_hex(32))"
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Modes d'Utilisation
|
|
|
|
### Mode Développement (Build Local + Hot-Reload)
|
|
|
|
**Utilise automatiquement** : `compose.yaml` + `compose.override.yaml`
|
|
|
|
```bash
|
|
cd docker
|
|
|
|
# Démarrer avec build local et volumes montés
|
|
docker compose up
|
|
|
|
# Rebuild après modification du code
|
|
docker compose up --build
|
|
|
|
# Voir les logs en temps réel
|
|
docker compose logs -f
|
|
|
|
# Arrêter
|
|
docker compose down
|
|
```
|
|
|
|
**Caractéristiques du mode dev** :
|
|
- ✅ Build local des images depuis `../backend` et `../frontend`
|
|
- ✅ Volumes montés pour hot-reload backend
|
|
- ✅ Logs DEBUG activés
|
|
- ✅ Health checks moins stricts
|
|
|
|
### Mode Production (Images du Registre)
|
|
|
|
**Utilise uniquement** : `compose.yaml` (sans override)
|
|
|
|
```bash
|
|
cd docker
|
|
|
|
# Démarrer avec images pré-buildées du registre
|
|
docker compose -f compose.yaml up -d
|
|
|
|
# Voir le statut
|
|
docker compose -f compose.yaml ps
|
|
|
|
# Voir les logs
|
|
docker compose -f compose.yaml logs -f
|
|
|
|
# Arrêter
|
|
docker compose -f compose.yaml down
|
|
```
|
|
|
|
**Caractéristiques du mode production** :
|
|
- ✅ Images pré-buildées depuis le registre Docker
|
|
- ✅ Pas de volumes de code (images complètes)
|
|
- ✅ Logs INFO/WARNING
|
|
- ✅ Health checks stricts
|
|
- ✅ Restart automatique (`unless-stopped`)
|
|
|
|
---
|
|
|
|
## 🐋 Utilisation avec Podman
|
|
|
|
### Pourquoi Podman ?
|
|
|
|
- **Sans privilèges root** : Exécution en mode utilisateur (rootless)
|
|
- **Compatible Docker** : Même syntaxe que docker-compose
|
|
- **Plus sécurisé** : Pas de daemon en arrière-plan
|
|
|
|
### Installation Podman
|
|
|
|
```bash
|
|
# Debian/Ubuntu
|
|
sudo apt install podman podman-compose
|
|
|
|
# Fedora/RHEL
|
|
sudo dnf install podman podman-compose
|
|
|
|
# Arch Linux
|
|
sudo pacman -S podman podman-compose
|
|
```
|
|
|
|
### Commandes Podman
|
|
|
|
```bash
|
|
# Remplacer 'docker compose' par 'podman-compose'
|
|
cd docker
|
|
podman-compose up -d
|
|
podman-compose logs -f
|
|
podman-compose down
|
|
|
|
# Ou utiliser l'alias podman (compatible Docker CLI)
|
|
alias docker=podman
|
|
docker compose up -d
|
|
```
|
|
|
|
---
|
|
|
|
## 🗄️ Gestion de la Base de Données
|
|
|
|
### Backup
|
|
|
|
```bash
|
|
# Backup manuel
|
|
docker compose exec backend sh -c "cp /data/school_management.db /data/backup_$(date +%Y%m%d_%H%M%S).db"
|
|
|
|
# Ou depuis l'hôte
|
|
cp ../data/school_management.db ../data/backup_$(date +%Y%m%d_%H%M%S).db
|
|
```
|
|
|
|
### Restauration
|
|
|
|
```bash
|
|
# Restaurer depuis un backup
|
|
docker compose stop backend
|
|
cp ../data/backup_YYYYMMDD_HHMMSS.db ../data/school_management.db
|
|
docker compose start backend
|
|
```
|
|
|
|
### Migration depuis v1
|
|
|
|
```bash
|
|
# Si vous avez une base v1 Flask
|
|
cp ../instance/school_management.db ../data/school_management.db
|
|
docker compose restart backend
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Healthcheck et Monitoring
|
|
|
|
Les services incluent des healthchecks automatiques :
|
|
|
|
```bash
|
|
# Vérifier la santé du backend
|
|
curl http://localhost:8080/api/v2/health
|
|
|
|
# Vérifier la santé du frontend
|
|
curl http://localhost:8081/
|
|
|
|
# Voir le statut Docker
|
|
docker compose ps
|
|
```
|
|
|
|
**Réponse attendue du backend :**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"database": "connected",
|
|
"tables": 12,
|
|
"classes": 5,
|
|
"students": 155
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🚨 Dépannage
|
|
|
|
### Le backend ne démarre pas
|
|
|
|
```bash
|
|
# Voir les logs
|
|
docker compose logs backend
|
|
|
|
# Vérifier la configuration
|
|
docker compose exec backend env | grep DATABASE_URL
|
|
|
|
# Recréer le conteneur
|
|
docker compose up -d --force-recreate backend
|
|
```
|
|
|
|
### Le frontend ne charge pas
|
|
|
|
```bash
|
|
# Vérifier Nginx
|
|
docker compose logs frontend
|
|
|
|
# Tester la connectivité au backend
|
|
docker compose exec frontend curl http://backend:8000/api/v2/health
|
|
|
|
# Rebuild le frontend
|
|
docker compose build frontend
|
|
docker compose up -d frontend
|
|
```
|
|
|
|
### Problème de permissions (base de données)
|
|
|
|
```bash
|
|
# Ajuster les permissions
|
|
chmod 666 ../data/school_management.db
|
|
chmod 755 ../data/
|
|
```
|
|
|
|
### Les changements de code ne sont pas pris en compte
|
|
|
|
```bash
|
|
# Rebuild complet
|
|
docker compose down
|
|
docker compose build --no-cache
|
|
docker compose up -d
|
|
```
|
|
|
|
---
|
|
|
|
## 🌐 Déploiement Production
|
|
|
|
### Configuration Nginx (hôte)
|
|
|
|
Si vous utilisez Nginx sur l'hôte pour le reverse proxy :
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name notytex.example.com;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:8081;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
}
|
|
```
|
|
|
|
### HTTPS avec Let's Encrypt
|
|
|
|
```bash
|
|
# Installer certbot
|
|
sudo apt install certbot python3-certbot-nginx
|
|
|
|
# Obtenir un certificat
|
|
sudo certbot --nginx -d notytex.example.com
|
|
```
|
|
|
|
### Systemd Service
|
|
|
|
Créez `/etc/systemd/system/notytex.service` :
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Notytex Docker Compose
|
|
Requires=docker.service
|
|
After=docker.service
|
|
|
|
[Service]
|
|
Type=oneshot
|
|
RemainAfterExit=yes
|
|
WorkingDirectory=/path/to/notytex/docker
|
|
ExecStart=/usr/bin/docker compose -f compose.yaml up -d
|
|
ExecStop=/usr/bin/docker compose -f compose.yaml down
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
Activer :
|
|
```bash
|
|
sudo systemctl enable notytex
|
|
sudo systemctl start notytex
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 Monitoring
|
|
|
|
### Logs centralisés
|
|
|
|
```bash
|
|
# Tous les logs en temps réel
|
|
docker compose logs -f
|
|
|
|
# Logs des dernières 24h
|
|
docker compose logs --since 24h
|
|
|
|
# Recherche dans les logs
|
|
docker compose logs | grep ERROR
|
|
```
|
|
|
|
### Métriques Docker
|
|
|
|
```bash
|
|
# Utilisation ressources
|
|
docker stats
|
|
|
|
# Espace disque
|
|
docker system df
|
|
|
|
# Nettoyage
|
|
docker system prune -a
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 Sécurité - Checklist Production
|
|
|
|
- [ ] Changer `SECRET_KEY` (unique et aléatoire)
|
|
- [ ] Configurer CORS avec vos domaines réels
|
|
- [ ] Utiliser HTTPS en production
|
|
- [ ] Limiter les ports exposés (firewall)
|
|
- [ ] Mettre en place des backups automatiques
|
|
- [ ] Configurer des alertes monitoring
|
|
- [ ] Restreindre les permissions fichiers
|
|
- [ ] Mettre à jour régulièrement les images Docker
|
|
|
|
---
|
|
|
|
## 🔄 CI/CD - Images du Registre
|
|
|
|
### Configuration CI/CD
|
|
|
|
Le projet inclut `.gitea/workflows/docker-publish.yml` pour la construction automatique des images Docker.
|
|
|
|
**Déclencheurs** :
|
|
- Push sur `main` ou `rewrite`
|
|
- Tags `v*` (releases)
|
|
- Déclenchement manuel
|
|
|
|
**Variables requises (Secrets)** :
|
|
- `REGISTRY_URL` - URL de votre registre Docker
|
|
- `REGISTRY_NAMESPACE` - Namespace/organisation
|
|
- `REGISTRY_USERNAME` - Nom d'utilisateur pour le registre
|
|
- `REGISTRY_PASSWORD` - Mot de passe ou token pour le registre
|
|
|
|
### Utiliser les images du registre
|
|
|
|
```bash
|
|
# 1. Se connecter au registre (si privé)
|
|
docker login <REGISTRY_URL>
|
|
|
|
# 2. Pull des images
|
|
docker pull <REGISTRY_URL>/<NAMESPACE>/notytex-backend:latest
|
|
docker pull <REGISTRY_URL>/<NAMESPACE>/notytex-frontend:latest
|
|
|
|
# 3. Configurer .env
|
|
REGISTRY_URL=registry.example.com
|
|
REGISTRY_NAMESPACE=myorg
|
|
IMAGE_TAG=latest
|
|
|
|
# 4. Démarrer
|
|
docker compose -f compose.yaml up -d
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Ressources Recommandées
|
|
|
|
- **Backend** : 512MB RAM, 0.5 CPU
|
|
- **Frontend** : 256MB RAM, 0.25 CPU
|
|
- **Total** : ~1GB RAM, 1 CPU pour 50 utilisateurs
|
|
|
|
---
|
|
|
|
## 📞 Support
|
|
|
|
En cas de problème :
|
|
|
|
1. Vérifiez les logs : `docker compose logs`
|
|
2. Testez les healthchecks
|
|
3. Consultez la documentation principale : `../README.md`
|
|
4. Vérifiez les issues GitHub
|
|
|
|
---
|
|
|
|
**Développé avec ❤️ pour simplifier le déploiement de Notytex**
|