540 lines
12 KiB
Markdown
540 lines
12 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
|
|
|
|
> 💡 **Note Podman** : Les Dockerfiles utilisent des images Docker Hub qualifiées (`docker.io/library/*`) pour compatibilité Podman
|
|
|
|
### Installation en 3 commandes
|
|
|
|
```bash
|
|
# 1. Configurer l'environnement
|
|
cp .env.docker .env
|
|
# Éditez .env et changez SECRET_KEY !
|
|
|
|
# 2. Créer le répertoire de données
|
|
mkdir -p data
|
|
cp school_management.db data/
|
|
|
|
# 3. Démarrer les services
|
|
docker-compose up -d
|
|
```
|
|
|
|
**Accès :**
|
|
- Frontend : http://localhost:8081
|
|
- API : http://localhost:8080
|
|
- Documentation API : http://localhost:8080/api/v2/docs
|
|
|
|
> 💡 **Compatibilité Podman** : Les ports 8080/8081 (>1024) permettent l'utilisation sans privilèges root
|
|
|
|
---
|
|
|
|
## 📂 Architecture Docker
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ Nginx:80 │
|
|
│ (Frontend Vue.js) │
|
|
└────────────────┬────────────────────────────────┘
|
|
│
|
|
│ Proxy /api → backend:8000
|
|
│
|
|
┌────────────────▼────────────────────────────────┐
|
|
│ FastAPI:8000 │
|
|
│ (Backend Python) │
|
|
└────────────────┬────────────────────────────────┘
|
|
│
|
|
│ SQLite
|
|
│
|
|
┌────────────────▼────────────────────────────────┐
|
|
│ Volume: ./data │
|
|
│ (Base de données SQLite) │
|
|
└─────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Variables d'Environnement
|
|
|
|
Éditez le fichier `.env` :
|
|
|
|
```bash
|
|
# Clé secrète (OBLIGATOIRE - générez-en une nouvelle !)
|
|
SECRET_KEY=votre-cle-secrete-unique-min-32-chars
|
|
|
|
# Base de données
|
|
DATABASE_URL=sqlite+aiosqlite:////data/school_management.db
|
|
|
|
# CORS (ajoutez vos domaines)
|
|
CORS_ORIGINS=["http://localhost","https://votre-domaine.com"]
|
|
|
|
# Email (optionnel)
|
|
SMTP_HOST=smtp.gmail.com
|
|
SMTP_PORT=587
|
|
SMTP_USERNAME=votre-email@gmail.com
|
|
SMTP_PASSWORD=votre-mot-de-passe-app
|
|
EMAIL_FROM=votre-email@gmail.com
|
|
```
|
|
|
|
### Générer une SECRET_KEY
|
|
|
|
```bash
|
|
python -c "import secrets; print(secrets.token_hex(32))"
|
|
```
|
|
|
|
---
|
|
|
|
## 🐋 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'
|
|
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
|
|
```
|
|
|
|
> ✅ **Les Dockerfiles sont configurés avec des images qualifiées** (`docker.io/library/*`) pour éviter les erreurs de registre
|
|
|
|
---
|
|
|
|
## 🛠️ Commandes Docker
|
|
|
|
### Démarrage
|
|
|
|
```bash
|
|
# Démarrer en arrière-plan
|
|
docker-compose up -d
|
|
|
|
# Voir les logs
|
|
docker-compose logs -f
|
|
|
|
# Logs d'un service spécifique
|
|
docker-compose logs -f backend
|
|
docker-compose logs -f frontend
|
|
```
|
|
|
|
### Arrêt
|
|
|
|
```bash
|
|
# Arrêter les services
|
|
docker-compose stop
|
|
|
|
# Arrêter et supprimer les conteneurs
|
|
docker-compose down
|
|
|
|
# Arrêter et supprimer tout (conteneurs + volumes)
|
|
docker-compose down -v
|
|
```
|
|
|
|
### Rebuild
|
|
|
|
```bash
|
|
# Rebuild après modification du code
|
|
docker-compose build
|
|
|
|
# Rebuild et redémarrage
|
|
docker-compose up -d --build
|
|
|
|
# Rebuild un service spécifique
|
|
docker-compose build backend
|
|
docker-compose up -d backend
|
|
```
|
|
|
|
### Inspection
|
|
|
|
```bash
|
|
# Statut des services
|
|
docker-compose ps
|
|
|
|
# Santé des services
|
|
docker-compose ps -a
|
|
|
|
# Entrer dans un conteneur
|
|
docker-compose exec backend sh
|
|
docker-compose exec frontend sh
|
|
```
|
|
|
|
---
|
|
|
|
## 🗄️ Gestion de la Base de Données
|
|
|
|
### Backup
|
|
|
|
```bash
|
|
# Créer un backup
|
|
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
|
|
|
|
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
|
|
|
|
# Renouvellement automatique est configuré
|
|
```
|
|
|
|
### 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
|
|
ExecStart=/usr/bin/docker-compose up -d
|
|
ExecStop=/usr/bin/docker-compose 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
|
|
|
|
### Mise à jour des images de base
|
|
|
|
```bash
|
|
# Pull les dernières images
|
|
docker-compose pull
|
|
|
|
# Rebuild avec nouvelles images
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
---
|
|
|
|
## 📦 Multi-environnements
|
|
|
|
### Développement (Build Local)
|
|
|
|
```bash
|
|
# Build et exécution locale (par défaut)
|
|
docker-compose up -d --build
|
|
|
|
# Avec Podman
|
|
podman-compose up -d --build
|
|
```
|
|
|
|
### Production (Images du Registre)
|
|
|
|
```bash
|
|
# Configurer les variables d'environnement pour votre registre
|
|
export REGISTRY_URL=registry.example.com # Votre registre Docker
|
|
export REGISTRY_NAMESPACE=myorganization # Votre namespace/organisation
|
|
export IMAGE_TAG=latest # Ou version spécifique (v2.0.0)
|
|
|
|
# Démarrer avec les images du registre
|
|
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
|
|
|
# Ou avec Podman
|
|
podman-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
**Exemples de registres** :
|
|
- **Gitea** : `registry.example.com/namespace/notytex-backend:latest`
|
|
- **GitHub** : `ghcr.io/username/notytex-backend:latest`
|
|
- **Docker Hub** : `docker.io/username/notytex-backend:latest`
|
|
- **GitLab** : `registry.gitlab.com/username/notytex-backend:latest`
|
|
|
|
> 💡 Les images peuvent être construites automatiquement par CI/CD (Gitea Actions, GitHub Actions, GitLab CI)
|
|
|
|
---
|
|
|
|
## 🔄 CI/CD - Images du Registre
|
|
|
|
### Configuration CI/CD
|
|
|
|
Le fichier `.gitea/workflows/docker-publish.yml` configure la construction automatique des images Docker.
|
|
|
|
**Déclencheurs** :
|
|
- Push sur `main` ou `rewrite`
|
|
- Tags `v*` (releases)
|
|
- Déclenchement manuel
|
|
|
|
**Variables requises (Secrets Gitea/GitHub)** :
|
|
- `REGISTRY_URL` - URL de votre registre Docker
|
|
- `REGISTRY_NAMESPACE` - Namespace/organisation (optionnel, défaut: `lafrite`)
|
|
- `REGISTRY_USERNAME` - Nom d'utilisateur pour le registre
|
|
- `REGISTRY_PASSWORD` - Mot de passe ou token pour le registre
|
|
|
|
**Artefacts produits** :
|
|
- `<registry>/<namespace>/notytex-backend:latest`
|
|
- `<registry>/<namespace>/notytex-backend:<branch>`
|
|
- `<registry>/<namespace>/notytex-frontend:latest`
|
|
- `<registry>/<namespace>/notytex-frontend:<branch>`
|
|
|
|
### Utiliser les images du registre
|
|
|
|
```bash
|
|
# 1. Se connecter au registre (si privé)
|
|
docker login <REGISTRY_URL>
|
|
# Ou avec Podman
|
|
podman 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 les variables
|
|
export REGISTRY_URL=registry.example.com
|
|
export REGISTRY_NAMESPACE=myorg
|
|
export IMAGE_TAG=latest
|
|
|
|
# 4. Démarrer avec docker-compose.prod.yml
|
|
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
### Avantages des images pré-construites
|
|
|
|
✅ **Déploiement rapide** : Pas de compilation sur le serveur
|
|
✅ **Reproductibilité** : Même image en dev/staging/prod
|
|
✅ **Multi-architecture** : Support AMD64 et ARM64
|
|
✅ **Cache optimisé** : Build incrémental via GitHub Actions cache
|
|
✅ **Versioning** : Tags par branche et version
|
|
|
|
---
|
|
|
|
## 🎯 Performances
|
|
|
|
### Optimisations
|
|
|
|
1. **Build multi-stage** : Réduit la taille des images
|
|
2. **Cache des dépendances** : Accélère les rebuilds
|
|
3. **Gzip Nginx** : Compression des assets
|
|
4. **Cache statique** : Headers cache 1 an pour JS/CSS
|
|
5. **Healthchecks** : Détection automatique des problèmes
|
|
|
|
### 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 : `README.md`
|
|
4. Vérifiez les issues GitHub
|
|
|
|
---
|
|
|
|
**Développé avec ❤️ pour simplifier le déploiement de Notytex**
|