Nginx, VPS, proxy et CDN : déployer Éclair

Déployer Éclair sur un VPS, derrière un proxy ou un CDN, revient à reproduire ce que le .htaccess fait sur un mutualisé : protéger les dossiers internes, tout envoyer à index.php, compresser et mettre en cache les fichiers statiques. Cette leçon donne une configuration Nginx commentée, les réglages HTTPS, proxy et Cloudflare, un exemple Docker et les vérifications finales.

Ce que Nginx doit reproduire du .htaccess

Nginx ignore les fichiers .htaccess. Sa configuration doit donc garantir les mêmes protections :

L'en-tête Authorization, que le .htaccess doit recopier pour le connecteur MCP, est transmis d'office par Nginx à PHP-FPM.

La configuration Nginx commentée

Les règles reprennent la section Nginx du guide officiel d'Éclair ; les lignes marquées « ajout » complètent l'exemple pour un vrai serveur. root désigne le dossier qui reçoit le contenu du dossier eclair de l'archive.

server {
    listen 80;
    listen [::]:80;
    server_name exemple.fr www.exemple.fr;
    root /var/www/eclair;
    index index.php;

    client_max_body_size 24m;            # ajout : images jusqu'à 20 Mo (Nginx : 1 Mo par défaut)
    gzip on;                             # ajout : compression, comme le .htaccess
    gzip_types text/plain text/css text/xml text/markdown application/javascript
               application/json application/xml application/rss+xml image/svg+xml;

    # Dossiers internes et fichiers cachés, sauf .well-known (découverte OAuth)
    location ~ ^/(app|data|cache)(/|$) { return 404; }
    location ~ /\.(?!well-known/) { return 404; }

    # Médias : images et polices seulement
    location ^~ /media/ {
        location ~* \.(php\d?|phtml|phar|s?html?|svgz?|xml|js)$ { return 404; }
        add_header X-Content-Type-Options nosniff;
        add_header Content-Security-Policy "default-src 'none'; img-src 'self'; sandbox";  # ajout, comme media/.htaccess
        expires 1y;
    }

    # Fichiers statiques versionnés : cache navigateur d'un an
    location ~* \.(webp|avif|jpe?g|png|gif|ico|css|js|woff2)$ { expires 1y; add_header Cache-Control "public, immutable"; }

    # Tout le reste passe par le contrôleur frontal
    location / { try_files $uri /index.php$is_args$args; }

    location = /index.php {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        fastcgi_pass unix:/run/php/php-fpm.sock;   # à adapter, par exemple /run/php/php8.3-fpm.sock
        fastcgi_buffering off;                     # conseillé par le guide : assistant IA au fil de l'eau
        fastcgi_read_timeout 300s;                 # ajout : demandes à l'IA longues (60 s par défaut)
    }

    # Aucun autre script PHP
    location ~ \.php$ { return 404; }
}

Trois réglages méritent une explication :

• client_max_body_size : Nginx refuse par défaut les requêtes de plus de 1 Mo (erreur 413), alors qu'Éclair accepte des images de 20 Mo. Règle aussi upload_max_filesize et post_max_size dans le php.ini de PHP-FPM.
• fastcgi_buffering off : l'assistant IA répond en flux. Éclair envoie déjà X-Accel-Buffering: no, que Nginx respecte par défaut ; la directive couvre les configurations qui l'ignorent.
• fastcgi_read_timeout : « Créer avec l'IA » répond d'un bloc après 20 à 60 secondes, et Éclair s'accorde jusqu'à 300 secondes, quand Nginx coupe après 60 secondes de silence.

sudo nginx -t && sudo systemctl reload nginx
# Éclair n'écrit que dans data/, cache/ et media/
sudo chown -R www-data:www-data /var/www/eclair/data /var/www/eclair/cache /var/www/eclair/media

HTTPS avec Certbot, puis les réglages d'Éclair

sudo certbot --nginx -d exemple.fr -d www.exemple.fr

Certbot obtient un certificat Let's Encrypt, ajoute l'écoute sur le port 443 au bloc server et peut rediriger le HTTP vers le HTTPS. Installe ensuite Éclair en ouvrant https://exemple.fr : l'assistant enregistre l'adresse telle que tu l'as ouverte, et coche déjà Forcer HTTPS. Puis, dans l'administration :

1. Ouvre Sécurité : l'adresse du site doit être vérifiée. Sinon, clique sur Vérifier l'adresse du site.
2. Dans Réglages › Avancé, vérifie que Forcer HTTPS est coché. Éclair refuse de l'activer tant que tu n'es pas connecté en https.
3. Laisse coché Rediriger vers l'adresse officielle : une seule version du site, avec ou sans www, dès que l'adresse est vérifiée.
4. Une fois tout stable, coche HSTS. Éclair envoie alors Strict-Transport-Security: max-age=31536000, soit un an, sans les sous-domaines. Les navigateurs refuseront ensuite le http:// pour ton domaine : ne l'active donc jamais pendant des essais.

N'ajoute pas HSTS dans Nginx en plus : l'en-tête partirait deux fois. Pour le gérer dans Nginx, décoche l'option d'Éclair, et retiens qu'un add_header placé dans un bloc location masque ceux du bloc server.

Comment déployer Éclair derrière un proxy inverse ?

Quand un autre serveur termine le HTTPS (Nginx devant un conteneur, Caddy, Traefik…), PHP reçoit du HTTP. Éclair tient la connexion pour sécurisée si la variable HTTPS est active, si le port vaut 443, ou si la requête porte X-Forwarded-Proto: https ou X-Forwarded-SSL: on. Le proxy doit donc envoyer X-Forwarded-Proto et conserver l'en-tête Host, qu'Éclair compare à son adresse officielle.

# Nginx en proxy inverse devant Éclair (conteneur publié sur 127.0.0.1:8080)
location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;                  # hôte d'origine, comparé à l'adresse du site
    proxy_set_header X-Forwarded-Proto $scheme;   # https, tel que le visiteur le voit
    proxy_set_header X-Real-IP $remote_addr;      # vraie adresse IP du visiteur
    proxy_buffering off;                          # flux de l'assistant IA
    proxy_read_timeout 300s;
    client_max_body_size 24m;
}

Derrière un proxy, PHP voit l'adresse IP du proxy : les limites anti-bruteforce et celles du formulaire frapperaient tous les visiteurs à la fois. Dans Réglages › Avancé › Site derrière un proxy / CDN, choisis l'en-tête qui porte la vraie adresse. Éclair ne le lit que si tu l'as choisi, et ne garde de X-Forwarded-For que la dernière adresse, celle ajoutée par le proxy le plus proche.

Ne choisis un en-tête que si le site est vraiment derrière ce service : sinon, un visiteur pourrait l'écrire lui-même et contourner les limites. Derrière Cloudflare, n'accepte que les connexions venant des adresses publiées par Cloudflare.

Cloudflare : ce qu'il faut régler

• Chiffrement : mode SSL/TLS « Full (strict) », avec un vrai certificat sur ton serveur, celui de Certbot par exemple.
• Pare-feu et anti-robots : laisse passer /_eclair/ et /.well-known/, sinon Claude et ChatGPT ne joignent ni le connecteur MCP ni son autorisation.
• Cache : les fichiers statiques sont déjà marqués pour un an. Ne mets pas le HTML en cache chez Cloudflare : Éclair vide son propre cache à chaque publication, pas celui de Cloudflare, et l'administration comme /_eclair/ ne doivent jamais y finir.
• Options qui injectent des scripts : selon la documentation de Cloudflare, Rocket Loader exige ajax.cloudflare.com dans script-src, et Web Analytics static.cloudflareinsights.com. La CSP d'Éclair n'autorise que les scripts du domaine : laisse ces options désactivées.
• Adresse IP : choisis « Cloudflare » dans Réglages › Avancé › Site derrière un proxy / CDN.

Comment déployer Éclair avec Docker ?

Voici un exemple de départ, à adapter, fondé sur l'image officielle php:8.3-apache. Il garde Apache pour que le .htaccess d'Éclair s'applique tel quel. Place ce Dockerfile à côté du dossier eclair décompressé.

# Exemple de départ, à adapter : Éclair 1.8 sur l'image officielle PHP 8.3 + Apache
FROM php:8.3-apache

# Déjà présentes dans l'image : mbstring, json, dom, session, zlib, curl, openssl, sodium, Argon2id.
# À ajouter : gd avec JPEG et WebP (images), zip (sauvegardes), exif (photos de téléphone redressées).
RUN apt-get update \
 && apt-get install -y --no-install-recommends libjpeg62-turbo-dev libpng-dev libwebp-dev libzip-dev \
 && docker-php-ext-configure gd --with-jpeg --with-webp \
 && docker-php-ext-install -j"$(nproc)" gd zip exif \
 && rm -rf /var/lib/apt/lists/*

# Modules utilisés par le .htaccess : réécriture, en-têtes, compression (sans effet si déjà actif)
RUN a2enmod rewrite headers deflate

# .htaccess autorisés : l'image le fait déjà pour /var/www/ (docker-php.conf), on le rend explicite
RUN printf '%s\n' '<Directory /var/www/html>' '    AllowOverride All' '</Directory>' \
      > /etc/apache2/conf-available/eclair.conf \
 && a2enconf eclair

# Réglages PHP de production, envois d'images jusqu'à 20 Mo
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" \
 && printf '%s\n' 'upload_max_filesize = 20M' 'post_max_size = 24M' > "$PHP_INI_DIR/conf.d/eclair.ini"

# Le contenu du dossier eclair de l'archive, fichiers cachés compris
COPY --chown=www-data:www-data eclair/ /var/www/html/

# compose.yaml : données et médias persistants, port réservé au proxy HTTPS de la machine
services:
  eclair:
    build: .
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - eclair-data:/var/www/html/data
      - eclair-media:/var/www/html/media
volumes:
  eclair-data:
  eclair-media:

docker compose up -d --build lance le site sur le port 8080 de la machine, derrière le proxy HTTPS de la section précédente. Les volumes nommés gardent data/ et media/ d'une version à l'autre : pour mettre à jour, remplace le dossier eclair par celui de la nouvelle archive et reconstruis l'image. L'image officielle active aussi OPcache par défaut (Dockerfile consulté le 1er novembre 2026).

docker compose exec eclair php -r 'var_dump(function_exists("imagewebp"));'   # bool(true)
docker compose exec eclair apache2ctl -M | grep -E 'rewrite|headers|deflate'

Vérifications après le déploiement

SITE=https://exemple.fr
# 1. Fichiers internes inaccessibles : 404 attendu pour chacun
for f in /data/site.php /data/users.php /app/bootstrap.php /cache/runtime.php /data/.htaccess; do
  printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' "$SITE$f")" "$f"
done
# 2. Réécriture d'URL : le contrôleur répond « ok »
curl -s "$SITE/__eclair/ping"; echo
# 3. Cache statique : X-Cache: HIT au deuxième appel
curl -sI "$SITE/" > /dev/null; curl -sI "$SITE/" | grep -i x-cache
# 4. Connecteur MCP activé : 401 et en-tête WWW-Authenticate
curl -si -X POST "$SITE/_eclair/mcp" | grep -i -E '^HTTP|www-authenticate'

Termine dans l'administration : la page Sécurité doit montrer un test de protection au vert et une adresse vérifiée, ce qui suppose que le serveur puisse s'appeler lui-même par son adresse publique, même depuis un conteneur. Envoie enfin une image de plus de 1 Mo dans Médias et, si l'assistant IA est activé, vérifie que sa réponse s'affiche au fil de l'eau.

À retenir

• Nginx ignore le .htaccess : recopie ses règles en gardant .well-known joignable pour le connecteur MCP.
• Pour déployer Éclair proprement, autorise des envois de 20 Mo et coupe le tampon FastCGI pour l'assistant IA.
• Derrière un proxy, envoie X-Forwarded-Proto et Host, et ne choisis un en-tête d'adresse IP que s'il existe vraiment.
• Avec Cloudflare : mode Full (strict), /_eclair/ et /.well-known/ ouverts, HTML hors cache, Rocket Loader coupé.
• L'exemple Docker garde Apache et le .htaccess d'origine, avec data/ et media/ dans des volumes.

Pour aller plus loin

• L'architecture d'Éclair : pourquoi chaque règle du .htaccess existe.
• Performance : garder 100 sur 100 : mesurer le site une fois déployé.
• Sécurité avancée et maintenance : droits des fichiers, sauvegardes et mises à jour.
• Connecter Claude à ton site : le connecteur MCP, qui exige HTTPS.
• Nginx : module FastCGI, pour fastcgi_buffering et fastcgi_read_timeout.
• Docker Hub : image officielle php, ses extensions et son php.ini.

Toutes les leçons du parcours