wiki/Catalogue-Self-Hosted/apps/app-nginx-proxy.md

---
title: nginx-proxy
created: 2026-06-06
updated: 2026-06-06
type: app
tags: [catalogue, reverse-proxy, docker, nginx, auto-hebergement, automation]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Reverse+Proxy, https://github.com/nginx-proxy/nginx-proxy]
---
# 🐳 nginx-proxy

> **Reverse proxy Nginx automatisé pour Docker** : démarre un conteneur Nginx qui détecte les autres conteneurs et génère la configuration automatiquement via la variable d'environnement `VIRTUAL_HOST`. L'ancêtre du reverse-proxy-as-a-container.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [github.com/nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) |
| **GitHub** | [nginx-proxy/nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) |
| **License** | MIT |
| **Langage** | Shell, Python (docker-gen) |
| **Étoiles GitHub** | 19.9k ⭐ |
| **Dernière MAJ** | 2026-05-27 |
| **Catégorie** | [[cat-reverse-proxy|Reverse Proxy]] |

## 📝 Description

**nginx-proxy** est le **pionnier du reverse proxy "Docker-native"** : un conteneur unique qui wrap **Nginx** + **docker-gen** (générateur de configs basé sur les métadonnées Docker). Quand un conteneur démarre avec `VIRTUAL_HOST=app.example.com`, nginx-proxy détecte l'événement, génère la conf Nginx, et reload — **zéro configuration manuelle**.

**Caractéristiques** :

- ✅ **Configuration par variables d'environnement** (`VIRTUAL_HOST`, `LETSENCRYPT_HOST`, `VIRTUAL_PORT`, etc.)
- ✅ **Auto-reload** : la conf se regénère à chaque démarrage/arrêt de conteneur
- ✅ **HTTPS automatique** via le compagnon [acme-companion](https://github.com/nginx-proxy/acme-companion) (Let's Encrypt)
- ✅ **WebSocket** supporté nativement
- ✅ **Multi-domaines** : un seul nginx-proxy peut gérer des centaines de sites
- ✅ **Single binary** côté final : juste Nginx sous le capot
- ✅ **Léger** : image basée sur `nginx:mainline` (~50 Mo)
- ✅ **MIT** : open source, maintenu par la communauté (et désormais par ZeroSSL)

**Positionnement** : c'est l'**ancêtre** des reverse proxies Docker. Avant lui, il fallait écrire des vhosts Nginx à la main. Avec lui, vous ne touchez plus jamais à un fichier de conf. **L'ancêtre conceptuel de Traefik** (qui a ensuite ajouté l'auto-discovery des labels, plus flexible).

**Limites** : c'est plus **rigide** que Traefik (variables d'env seulement, pas de labels) et **moins moderne** (pas d'API, pas de dashboard). Pour des stacks simples, il reste imbattable en simplicité. Pour des stacks complexes, Traefik a pris le dessus.

**Public cible** : utilisateurs qui veulent un reverse proxy **basique, solide, sans fioritures**, sur une stack Docker de taille petite à moyenne.

## 🚀 Installation

### Option 1 : Docker run (le plus simple)

```bash
docker run --detach \
  --name nginx-proxy \
  --publish 80:80 \
  --publish 443:443 \
  --volume /var/run/docker.sock:/tmp/docker.sock:ro \
  nginxproxy/nginx-proxy:1.11
```

C'est tout. nginx-proxy tourne, écoute Docker.

### Option 2 : Docker Compose (recommandé)

```yaml
# docker-compose.yml
version: '3.8'
services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy:1.11
    container_name: nginx-proxy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - html:/usr/share/nginx/html
      - certs:/etc/nginx/certs
    networks:
      - proxy

networks:
  proxy:
    name: proxy

volumes:
  html:
  certs:
```

### Exemple : ajouter un service à proxyfier

```yaml
# docker-compose.yml (à part ou dans le même stack)
services:
  whoami:
    image: traefik/whoami
    networks:
      - proxy
    environment:
      - VIRTUAL_HOST=whoami.example.com
      # Optionnel : HTTPS auto avec acme-companion
      - LETSENCRYPT_HOST=whoami.example.com
      - LETSENCRYPT_EMAIL=admin@example.com

networks:
  proxy:
    external: true  # Réseau partagé avec nginx-proxy
```

**Logique** : dès que `whoami` démarre, nginx-proxy détecte le label, génère le vhost, et route `whoami.example.com` vers le conteneur.

### Variante avec HTTPS automatique (acme-companion)

```yaml
# Ajouter à côté de nginx-proxy
services:
  acme-companion:
    image: nginxproxy/acme-companion:2.4
    container_name: nginx-proxy-acme
    restart: unless-stopped
    volumes_from:
      - nginx-proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - acme:/etc/acme.sh
    environment:
      - DEFAULT_EMAIL=admin@example.com
      - NGINX_PROXY_CONTAINER=nginx-proxy

volumes:
  acme:
```

## ⚙️ Configuration Initiale

1. **Créer un réseau Docker partagé** : `docker network create proxy`
2. **Lancer nginx-proxy** (ci-dessus)
3. **Pour chaque app à exposer** :
   - Définir `VIRTUAL_HOST=monapp.example.com`
   - Placer le conteneur sur le réseau `proxy`
   - **Exposer le port** (`EXPOSE 8080` dans le Dockerfile ou `--expose`)
4. **Pointer le DNS** : A record `monapp.example.com` → IP du serveur
5. **(Optionnel HTTPS)** Lancer `acme-companion` pour les certificats

> ⚠️ **Piège courant** : les conteneurs proxyfiés doivent **partager un réseau Docker** avec nginx-proxy. Sur le réseau bridge par défaut, ça marche "par chance" mais en user-defined network, il faut faire `networks: [proxy: { external: true }]`.

## 🔄 Alternatives

### Open Source
- [[app-traefik]] — Plus moderne, auto-discovery par labels (pas env)
- [[app-caddy]] — HTTPS automatique natif sans compagnon
- [[app-nginx-proxy-manager]] — Nginx + GUI web, plus user-friendly
- [[app-haproxy]] — Load balancer pur, pas auto-discovery
- [jwilder/nginx-proxy](https://github.com/jwilder/nginx-proxy) — version originale (maintenant dépréciée, le projet est chez `nginx-proxy/nginx-proxy`)

### Propriétaires
- **AWS ALB** (Application Load Balancer)
- **Cloudflare Load Balancer**
- **F5 BIG-IP** (enterprise)
- **HAProxy Enterprise**

## 🔐 Sécurité

- **HTTPS** via Let's Encrypt (acme-companion) — **fortement recommandé**
- **Pas d'IP whitelisting natif** : à faire via une conf Nginx custom
- **Pas de rate limiting natif** : idem, conf custom
- **HSTS / headers sécurité** : à configurer dans la conf Nginx
- **Docker socket en lecture seule** : limit l'escalade de privilèges
- **Image régulièrement mise à jour** : suivre les releases

> 💡 **Astuce** : pour ajouter des middlewares (auth, rate-limit, headers), il faut créer un **fichier de conf custom** et le monter dans `/etc/nginx/conf.d/`. nginx-proxy n'a pas d'équivalent des middlewares Traefik.

## 📚 Ressources

- [Documentation officielle](https://github.com/nginx-proxy/nginx-proxy/tree/main/docs)
- [Docker Hub](https://hub.docker.com/r/nginxproxy/nginx-proxy)
- [acme-companion (HTTPS)](https://github.com/nginx-proxy/acme-companion)
- [Docker-gen](https://github.com/nginx-proxy/docker-gen)

## Pages Liées
- [[cat-reverse-proxy]] — Catégorie Reverse Proxy
- [[app-traefik]] — Successeur moderne
- [[app-nginx-proxy-manager]] — Variante avec GUI
- [[comparatif-reverse-proxy]] — Comparaison détaillée
- [[recettes-docker-compose]] — Templates d'intégration