infrastructure/docs/10-configuration-nginx-proxy-manager.md

Configuration Nginx Proxy Manager

Ce guide explique comment configurer Nginx Proxy Manager (NPM) pour l'utiliser avec le déploiement automatique d'applications via Woodpecker CI.

Vue d'ensemble

Nginx Proxy Manager permet de :

• Gérer facilement les reverse proxies
• Configurer automatiquement les certificats SSL avec Let's Encrypt
• Sécuriser l'accès aux applications avec des Access Lists
• Automatiser la configuration via l'API

Installation

Via Docker Compose

version: "3.9"

services:
  npm:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - '80:80'      # HTTP
      - '443:443'    # HTTPS
      - '81:81'      # Interface d'administration
    volumes:
      - npm-data:/data
      - npm-letsencrypt:/etc/letsencrypt
    networks:
      - gitgit_syoul_fr_gitea_net

volumes:
  npm-data:
  npm-letsencrypt:

networks:
  gitgit_syoul_fr_gitea_net:
    external: true

Accès initial

1. Accédez à l'interface : http://[IP-serveur]:81
2. Identifiants par défaut :
   • Email : admin@example.com
   • Mot de passe : changeme
3. IMPORTANT : Changez immédiatement le mot de passe !

Configuration de l'API

Obtenir un token API

Nginx Proxy Manager ne propose pas d'interface graphique pour créer des tokens API. Il faut utiliser l'API directement.

Méthode 1 : Via curl

curl -X POST http://192.168.42.144:81/api/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "votre_email@example.com",
    "secret": "votre_mot_de_passe"
  }'

Réponse attendue :

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_name": "API Token",
  "expires_at": null
}

Méthode 2 : Script automatique

Créez un script get-npm-token.sh :

#!/bin/bash
# get-npm-token.sh - Génère un token API pour Nginx Proxy Manager

set -e

NPM_URL=${1:-"http://localhost:81"}
EMAIL=${2:-"admin@example.com"}

echo "Génération du token API pour Nginx Proxy Manager..."
echo "URL: ${NPM_URL}"
echo "Email: ${EMAIL}"
echo ""

# Demander le mot de passe de manière sécurisée
read -sp "Mot de passe: " PASSWORD
echo ""

# Obtenir le token
RESPONSE=$(curl -s -X POST "${NPM_URL}/api/tokens" \
  -H "Content-Type: application/json" \
  -d "{
    \"identity\": \"${EMAIL}\",
    \"secret\": \"${PASSWORD}\"
  }")

# Extraire le token
TOKEN=$(echo "${RESPONSE}" | jq -r '.token')

if [ "${TOKEN}" = "null" ] || [ -z "${TOKEN}" ]; then
  echo "❌ Erreur lors de la génération du token"
  echo "Réponse: ${RESPONSE}"
  exit 1
fi

echo "✅ Token généré avec succès !"
echo ""
echo "Token: ${TOKEN}"
echo ""
echo "Pour l'utiliser dans Woodpecker CI :"
echo "1. Allez dans Woodpecker > Settings > Secrets"
echo "2. Ajoutez NPM_API_TOKEN avec la valeur ci-dessus"
echo "3. Ajoutez NPM_API_URL avec la valeur: ${NPM_URL}"

Usage :

chmod +x get-npm-token.sh
./get-npm-token.sh http://192.168.42.144:81 votre_email@example.com

Tester le token

Vérifiez que le token fonctionne :

TOKEN="votre-token-ici"
NPM_URL="http://192.168.42.144:81"

# Lister les proxy hosts
curl -H "Authorization: Bearer ${TOKEN}" \
  "${NPM_URL}/api/nginx/proxy-hosts"

# Obtenir les détails d'un proxy host
curl -H "Authorization: Bearer ${TOKEN}" \
  "${NPM_URL}/api/nginx/proxy-hosts/1"

Configuration dans Woodpecker CI

Ajouter les secrets

1. Connectez-vous à Woodpecker CI (https://ci.syoul.fr)
2. Allez dans Settings > Secrets
3. Ajoutez les secrets suivants :

Secret	Valeur	Description
NPM_API_URL	http://192.168.42.144:81	URL de votre Nginx Proxy Manager
NPM_API_TOKEN	votre-token-api	Token obtenu via l'API
DOMAIN_BASE	syoul.fr	Domaine de base pour les URLs (optionnel)

URL interne vs externe

Si Nginx Proxy Manager est dans le même réseau Docker que vos applications :

Utilisez l'URL interne :

NPM_API_URL=http://npm-manager:81  # Nom du conteneur

Ou l'IP interne :

NPM_API_URL=http://172.18.0.X:81  # IP du conteneur

Pour trouver le nom/IP du conteneur :

docker ps | grep nginx-proxy-manager
docker inspect nginx-proxy-manager | grep IPAddress

Utilisation de l'API

Créer un proxy host

curl -X POST "${NPM_API_URL}/api/nginx/proxy-hosts" \
  -H "Authorization: Bearer ${NPM_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_names": ["mon-app.syoul.fr"],
    "forward_scheme": "http",
    "forward_host": "172.18.0.10",
    "forward_port": 3000,
    "ssl_forced": true,
    "hsts_enabled": true,
    "hsts_subdomains": true,
    "block_exploits": true,
    "caching_enabled": true,
    "allow_websocket_upgrade": true
  }'

Mettre à jour un proxy host

PROXY_ID=1  # ID du proxy host

curl -X PUT "${NPM_API_URL}/api/nginx/proxy-hosts/${PROXY_ID}" \
  -H "Authorization: Bearer ${NPM_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "forward_host": "172.18.0.11",
    "forward_port": 3000
  }'

Supprimer un proxy host

PROXY_ID=1

curl -X DELETE "${NPM_API_URL}/api/nginx/proxy-hosts/${PROXY_ID}" \
  -H "Authorization: Bearer ${NPM_API_TOKEN}"

Lister tous les proxy hosts

curl -H "Authorization: Bearer ${NPM_API_TOKEN}" \
  "${NPM_API_URL}/api/nginx/proxy-hosts" | jq

Intégration avec le déploiement automatique

Dans .woodpecker.yml

Le pipeline Woodpecker utilise automatiquement ces secrets pour configurer les reverse proxies :

pipeline:
  deploy:
    environment:
      - NPM_API_URL=${NPM_API_URL}      # Secret Woodpecker
      - NPM_API_TOKEN=${NPM_API_TOKEN}  # Secret Woodpecker
      - DOMAIN_BASE=${DOMAIN_BASE:-syoul.fr}
    commands:
      # ... configuration automatique du proxy ...

Voir Déploiement d'applications pour plus de détails.

Configuration SSL

Certificats Let's Encrypt

Nginx Proxy Manager peut automatiquement obtenir des certificats SSL via Let's Encrypt :

1. Allez dans SSL Certificates
2. Cliquez sur Add SSL Certificate
3. Sélectionnez Let's Encrypt
4. Entrez le domaine (ex: mon-app.syoul.fr)
5. Cochez Use a DNS Challenge si nécessaire
6. Le certificat sera automatiquement renouvelé

Forcer HTTPS

Dans la configuration du proxy host, activez :

• SSL : Certificat SSL
• Force SSL : Redirige automatiquement HTTP vers HTTPS
• HSTS Enabled : Active HTTP Strict Transport Security

Access Lists (Listes de contrôle d'accès)

Créer une Access List

1. Allez dans Access Lists
2. Cliquez sur Add Access List
3. Configurez :
   • Name : Nom de la liste
   • Satisfy : any (au moins une règle) ou all (toutes les règles)
   • Rules : Ajoutez des règles d'autorisation

Types de règles

• IP Address : Autoriser/bloquer des IPs spécifiques
• Basic Auth : Authentification HTTP basique
• Client Certificate : Authentification par certificat client

Appliquer une Access List

Dans la configuration du proxy host :

1. Allez dans Advanced > Access List
2. Sélectionnez votre Access List
3. Sauvegardez

Bonnes pratiques

1. Sécurité

• ✅ Changez le mot de passe par défaut immédiatement
• ✅ Utilisez des tokens API avec expiration si possible
• ✅ Limitez l'accès à l'interface d'administration (firewall)
• ✅ Utilisez HTTPS pour l'interface d'administration si exposée

2. Organisation

• ✅ Utilisez des noms de domaines cohérents
• ✅ Documentez les proxy hosts créés manuellement
• ✅ Utilisez des Access Lists pour sécuriser les applications sensibles

3. Monitoring

• ✅ Surveillez les logs dans Audit Log
• ✅ Vérifiez régulièrement les certificats SSL
• ✅ Monitor les performances des reverse proxies

Dépannage

Le token API ne fonctionne pas

1. Vérifiez que l'email et le mot de passe sont corrects
2. Vérifiez que l'URL est accessible :

   curl http://192.168.42.144:81/api/nginx/proxy-hosts
   

3. Vérifiez les permissions de l'utilisateur dans NPM

Erreur "401 Unauthorized"

• Le token est invalide ou expiré
• Régénérez un nouveau token
• Vérifiez que le header Authorization: Bearer est correct

Erreur "Cannot connect to NPM API"

• Vérifiez que NPM est accessible depuis le conteneur Woodpecker
• Utilisez l'URL interne si dans le même réseau Docker
• Vérifiez les règles de firewall

Le proxy host n'est pas créé

1. Vérifiez les logs de Woodpecker
2. Vérifiez que le domaine n'existe pas déjà
3. Vérifiez les permissions du token API
4. Testez manuellement la création via curl

Exemples

Script complet de déploiement avec NPM

#!/bin/bash
# deploy-with-npm.sh

APP_NAME="mon-app"
APP_PORT=3000
APP_IP="172.18.0.10"
APP_URL="${APP_NAME}.syoul.fr"
NPM_API_URL="http://npm-manager:81"
NPM_API_TOKEN="votre-token"

# Vérifier si le proxy existe
EXISTING_PROXY=$(curl -s -H "Authorization: Bearer ${NPM_API_TOKEN}" \
  "${NPM_API_URL}/api/nginx/proxy-hosts" | \
  jq -r ".[] | select(.domain_names[] == \"${APP_URL}\") | .id" | head -1)

PROXY_DATA=$(cat <<EOF
{
  "domain_names": ["${APP_URL}"],
  "forward_scheme": "http",
  "forward_host": "${APP_IP}",
  "forward_port": ${APP_PORT},
  "ssl_forced": true,
  "hsts_enabled": true,
  "hsts_subdomains": true,
  "block_exploits": true,
  "caching_enabled": true,
  "allow_websocket_upgrade": true
}
EOF
)

if [ -n "${EXISTING_PROXY}" ]; then
  echo "Mise à jour du proxy existant..."
  curl -X PUT "${NPM_API_URL}/api/nginx/proxy-hosts/${EXISTING_PROXY}" \
    -H "Authorization: Bearer ${NPM_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "${PROXY_DATA}"
else
  echo "Création d'un nouveau proxy..."
  curl -X POST "${NPM_API_URL}/api/nginx/proxy-hosts" \
    -H "Authorization: Bearer ${NPM_API_TOKEN}" \
    -H "Content-Type: application/json" \
    -d "${PROXY_DATA}"
fi

echo "✅ Proxy configuré pour ${APP_URL}"

Références

• Documentation officielle Nginx Proxy Manager
• API Documentation
• Déploiement d'applications avec Woodpecker