feat: ajout documentation Nginx Proxy Manager et scripts de déploiement
- Documentation complète pour Nginx Proxy Manager (docs/10-configuration-nginx-proxy-manager.md) - Script get-npm-token.sh pour générer automatiquement les tokens API - Exemple complet de .woodpecker.yml avec logique inline de déploiement - Documentation déploiement applications avec URLs dynamiques (docs/09-deploiement-applications.md) - Script deploy.sh comme alternative optionnelle - Mise à jour README avec références aux nouvelles documentations
This commit is contained in:
408
docs/10-configuration-nginx-proxy-manager.md
Normal file
408
docs/10-configuration-nginx-proxy-manager.md
Normal file
@ -0,0 +1,408 @@
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```bash
|
||||
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** :
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_name": "API Token",
|
||||
"expires_at": null
|
||||
}
|
||||
```
|
||||
|
||||
#### Méthode 2 : Script automatique
|
||||
|
||||
Créez un script `get-npm-token.sh` :
|
||||
|
||||
```bash
|
||||
#!/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** :
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
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** :
|
||||
```yaml
|
||||
NPM_API_URL=http://npm-manager:81 # Nom du conteneur
|
||||
```
|
||||
|
||||
**Ou l'IP interne** :
|
||||
```yaml
|
||||
NPM_API_URL=http://172.18.0.X:81 # IP du conteneur
|
||||
```
|
||||
|
||||
Pour trouver le nom/IP du conteneur :
|
||||
```bash
|
||||
docker ps | grep nginx-proxy-manager
|
||||
docker inspect nginx-proxy-manager | grep IPAddress
|
||||
```
|
||||
|
||||
## Utilisation de l'API
|
||||
|
||||
### Créer un proxy host
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```yaml
|
||||
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](09-deploiement-applications.md) 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 :
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
#!/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](https://nginxproxymanager.com/)
|
||||
- [API Documentation](https://nginxproxymanager.com/guide/#api)
|
||||
- [Déploiement d'applications avec Woodpecker](09-deploiement-applications.md)
|
||||
|
||||
Reference in New Issue
Block a user