Guide de déploiement Portainer¶

Prérequis¶

Portainer installé sur le NAS Synology
Accès administrateur à Portainer
Images Docker publiées sur ghcr.io (via GitHub Actions)
Conteneur MongoDB existant et fonctionnel

Étape 1 : Vérifier le réseau Docker¶

Avant de créer la stack, vérifiez que le conteneur MongoDB est sur le bon réseau.

Via Portainer¶

Accéder à Containers
Cliquer sur le conteneur mongo
Vérifier la section Network → doit afficher bridge

Via Docker CLI (optionnel)¶

docker network inspect bridge | grep mongo -A 10

Étape 2 : Créer la stack Portainer¶

Accès à Portainer¶

Ouvrir Portainer : http://<nas-ip>:9000 (ou port configuré)
Se connecter avec les identifiants administrateur
Sélectionner l'environnement local

Création de la stack¶

Dans le menu latéral : Stacks → Add stack
Name: lmelp-back-office
Build method: Web editor
Copier le contenu de docker/deployment/docker-compose.yml

version: '3.8'

services:
  backend:
    image: ghcr.io/castorfou/lmelp-backend:latest
    container_name: lmelp-backend
    restart: unless-stopped

    environment:
      MONGODB_URL: mongodb://mongo:27017/masque_et_la_plume
      ENVIRONMENT: production
      API_HOST: 0.0.0.0
      API_PORT: 8000

    networks:
      - lmelp-network

    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

  frontend:
    image: ghcr.io/castorfou/lmelp-frontend:latest
    container_name: lmelp-frontend
    restart: unless-stopped

    ports:
      - "8080:80"

    depends_on:
      - backend

    networks:
      - lmelp-network

    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

networks:
  lmelp-network:
    external: true
    name: bridge

Cliquer sur Deploy the stack

Étape 3 : Vérifier le déploiement¶

Statut des conteneurs¶

Accéder à Stacks → lmelp-back-office
Vérifier que les 2 conteneurs affichent running (vert)
Attendre que les healthchecks passent au vert (peut prendre 30 secondes)

Logs des conteneurs¶

Backend¶

Cliquer sur lmelp-backend
Onglet Logs
Vérifier l'absence d'erreurs

Chercher le message de démarrage uvicorn :

INFO:     Uvicorn running on http://0.0.0.0:8000

Frontend¶

Cliquer sur lmelp-frontend
Onglet Logs
Vérifier le démarrage nginx sans erreur

Test de connectivité¶

Depuis le NAS (SSH)¶

Tester le backend :

curl http://localhost:8080/api

Résultat attendu :

{"status": "ok", "message": "Welcome to Back Office LMELP API"}

Depuis un navigateur (réseau local)¶

Accéder à http://<nas-ip>:8080

Vérifier : - Page d'accueil Vue.js s'affiche - Recherche fonctionne - Onglets de navigation fonctionnent

Étape 4 : Configurer le webhook Portainer¶

Le webhook permet le déploiement automatique après chaque push sur GitHub.

Créer le webhook¶

Dans Portainer : Stacks → lmelp-back-office
Cliquer sur l'icône Webhook (🔗)
Activer Enable webhook
Copier l'URL générée (format : http://<nas-ip>:9000/api/webhooks/<token>)

Tester le webhook manuellement¶

curl -X POST "http://<nas-ip>:9000/api/webhooks/<token>"

Vérifier dans Portainer que la stack se redéploie (pull des dernières images).

Configurer GitHub¶

Accéder au repository GitHub : https://github.com/castorfou/back-office-lmelp
Settings → Secrets and variables → Actions
Onglet Secrets
Cliquer New repository secret
Name: PORTAINER_WEBHOOK_URL
Secret: Coller l'URL du webhook Portainer
Cliquer Add secret

Note : On utilise un secret plutôt qu'une variable pour des raisons de sécurité, car l'URL du webhook donne accès au déploiement de votre stack.

Tester le déploiement automatique¶

Faire un commit sur la branche main
Attendre que GitHub Actions build les images (~5-10 min)
Vérifier dans Portainer que la stack se redéploie automatiquement
Consulter les logs pour voir les nouvelles images téléchargées

Étape 5 : Configuration avancée¶

Variables d'environnement personnalisées¶

Pour modifier les variables d'environnement sans éditer le docker-compose :

Stacks → lmelp-back-office → Editor
Modifier les valeurs dans la section environment
Cliquer Update the stack
Sélectionner Re-pull image and redeploy

Limites de ressources¶

Pour ajuster les limites CPU/RAM :

deploy:
  resources:
    limits:
      cpus: '2.0'        # Augmenter si nécessaire
      memory: 4G
    reservations:
      cpus: '1.0'
      memory: 1G

Politique de redémarrage¶

Options disponibles : - no : Ne jamais redémarrer automatiquement - always : Toujours redémarrer (même après reboot NAS) - unless-stopped : Redémarrer sauf si arrêt manuel (recommandé) - on-failure : Redémarrer uniquement en cas d'erreur

Troubleshooting¶

Les conteneurs ne démarrent pas¶

Symptôme : Conteneurs en état Exited ou Error

Solutions :

Vérifier les logs Portainer
Vérifier que les images sont bien téléchargées (pas d'erreur réseau)
Vérifier le réseau bridge existe :
```
docker network ls | grep bridge
```

Backend ne peut pas se connecter à MongoDB¶

Symptôme : Logs backend affichent Connection refused ou Unknown host

Solutions :

Vérifier que le conteneur mongo est démarré :
```
docker ps | grep mongo
```

Vérifier que mongo est sur le même réseau :

docker inspect mongo | grep -A 5 Networks
docker inspect lmelp-backend | grep -A 5 Networks

Tester la résolution DNS depuis le backend :
```
docker exec lmelp-backend ping mongo
```

Frontend affiche 502 Bad Gateway¶

Symptôme : Page d'accueil charge mais API retourne 502

Solutions :

Vérifier que le backend est healthy :
```
docker ps | grep lmelp-backend
```

Tester la connexion depuis le frontend :

docker exec lmelp-frontend curl http://backend:8000/

Vérifier la configuration nginx :

docker exec lmelp-frontend cat /etc/nginx/conf.d/default.conf

Le webhook ne se déclenche pas¶

Symptôme : Push sur GitHub mais pas de redéploiement

Solutions :

Vérifier que PORTAINER_WEBHOOK_URL est configuré dans GitHub
Consulter les logs GitHub Actions (onglet Actions)
Tester le webhook manuellement :
```
curl -X POST "$PORTAINER_WEBHOOK_URL"
```

Images non mises à jour après webhook¶

Symptôme : Webhook fonctionne mais anciennes images utilisées

Solutions :

Forcer le pull dans Portainer :
Stacks → lmelp-back-office → Editor
Cocher Re-pull images and redeploy
Update the stack
Vérifier que GitHub Actions a bien publié les nouvelles images :
https://github.com/castorfou/back-office-lmelp/pkgs/container/lmelp-backend
https://github.com/castorfou/back-office-lmelp/pkgs/container/lmelp-frontend

Rollback vers une version précédente¶

Identifier les versions disponibles¶

Accéder à GitHub Container Registry :
Backend : https://github.com/castorfou/back-office-lmelp/pkgs/container/lmelp-backend
Frontend : https://github.com/castorfou/back-office-lmelp/pkgs/container/lmelp-frontend
Noter le tag de la version souhaitée (ex: v1.0.0)

Déployer une version spécifique¶

Stacks → lmelp-back-office → Editor

Modifier les tags d'images :

backend:
  image: ghcr.io/castorfou/lmelp-backend:v1.0.0  # Au lieu de :latest
frontend:
  image: ghcr.io/castorfou/lmelp-frontend:v1.0.0

Cocher Re-pull images and redeploy
Update the stack

Maintenance régulière¶

Nettoyage des images inutilisées¶

Portainer accumule les anciennes images après chaque mise à jour.

Images → Sélectionner les images <none>
Cliquer Remove

Ou via CLI :

docker image prune -a

Vérification des healthchecks¶

Consulter régulièrement les healthchecks dans Portainer : - Containers → Colonne Health doit afficher vert

Surveillance des logs¶

Activer les alertes Portainer pour : - Conteneur arrêté - Healthcheck échoué - Utilisation RAM > 80%

Guide de déploiement Portainer¶

Prérequis¶

Étape 1 : Vérifier le réseau Docker¶

Via Portainer¶

Via Docker CLI (optionnel)¶

Étape 2 : Créer la stack Portainer¶

Accès à Portainer¶

Création de la stack¶

Étape 3 : Vérifier le déploiement¶

Statut des conteneurs¶

Logs des conteneurs¶

Backend¶

Frontend¶

Test de connectivité¶

Depuis le NAS (SSH)¶

Depuis un navigateur (réseau local)¶

Étape 4 : Configurer le webhook Portainer¶

Créer le webhook¶

Tester le webhook manuellement¶

Configurer GitHub¶

Tester le déploiement automatique¶

Étape 5 : Configuration avancée¶

Variables d'environnement personnalisées¶

Limites de ressources¶

Politique de redémarrage¶

Troubleshooting¶

Les conteneurs ne démarrent pas¶

Backend ne peut pas se connecter à MongoDB¶

Frontend affiche 502 Bad Gateway¶

Le webhook ne se déclenche pas¶

Images non mises à jour après webhook¶

Rollback vers une version précédente¶

Identifier les versions disponibles¶

Déployer une version spécifique¶

Maintenance régulière¶

Nettoyage des images inutilisées¶

Vérification des healthchecks¶

Surveillance des logs¶

Prochaines étapes¶