notytex/docker

🐳 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

# 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 :

# 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

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

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)

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

# 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

# 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

# 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

# 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

# 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 :

# 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 :

{
  "status": "healthy",
  "database": "connected",
  "tables": 12,
  "classes": 5,
  "students": 155
}

---

🚨 Dépannage

Le backend ne démarre pas

# 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

# 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)

# Ajuster les permissions
chmod 666 ../data/school_management.db
chmod 755 ../data/

Les changements de code ne sont pas pris en compte

# 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 :

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

# 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 :

[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 :

sudo systemctl enable notytex
sudo systemctl start notytex

---

📊 Monitoring

Logs centralisés

# 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

# 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

# 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