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

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