Proxy inverse
Servez votre documentation sur /docs avec nginx, Apache, Caddy, Traefik ou HAProxy. Inclut des extraits de configuration testés pour chaque proxy inverse.
Si vous utilisez déjà nginx, Apache, Caddy, Traefik ou HAProxy, ajoutez un bloc location/route qui redirige le trafic /docs vers votre sous-domaine Jamdesk.
Prérequis
- Accès à la configuration de votre serveur web
- Votre sous-domaine Jamdesk (disponible dans les paramètres du dashboard)
Si vous utilisez un sous-chemin personnalisé au lieu de /docs par défaut, remplacez /docs dans chaque bloc location/route ci-dessous (nginx, Apache, Caddy, Traefik, HAProxy) par votre sous-chemin. Mettez à jour la configuration à nouveau après tout renommage dans le dashboard.
nginx
Ajoutez un bloc location pour rediriger les requêtes /docs vers Jamdesk :
server {
listen 443 ssl;
server_name yoursite.com;
# Your existing configuration...
# Proxy /docs to Jamdesk
location /docs {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# Required for domain verification
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
# Next.js static assets (JS, CSS)
location /_next/ {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
}
# Jamdesk assets (fonts, images, branding)
location /_jd/ {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
}
}
Remplacez YOUR_SLUG par votre sous-domaine Jamdesk actuel.
La gestion du chemin est importante. L'URL proxy_pass n'a pas de chemin final, donc nginx conserve le chemin de la requête d'origine. Une requête vers /docs/page est redirigée vers jamdesk.app/docs/page. Si vous ajoutez une barre oblique finale (proxy_pass https://...jamdesk.app/), le préfixe /docs est supprimé. Conservez-le exactement comme indiqué ci-dessus.
Après avoir mis à jour votre configuration, rechargez nginx :
sudo nginx -t && sudo systemctl reload nginxApache
Utilisez mod_proxy pour rediriger les requêtes /docs vers Jamdesk :
<VirtualHost *:443>
ServerName yoursite.com
# Your existing configuration...
# Enable proxy modules
ProxyRequests Off
SSLProxyEngine On
# Proxy /docs to Jamdesk
ProxyPass /docs https://YOUR_SLUG.jamdesk.app/docs
ProxyPassReverse /docs https://YOUR_SLUG.jamdesk.app/docs
# Next.js static assets (JS, CSS)
ProxyPass /_next https://YOUR_SLUG.jamdesk.app/_next
ProxyPassReverse /_next https://YOUR_SLUG.jamdesk.app/_next
# Jamdesk assets (fonts, images, branding)
ProxyPass /_jd https://YOUR_SLUG.jamdesk.app/_jd
ProxyPassReverse /_jd https://YOUR_SLUG.jamdesk.app/_jd
<Location /docs>
RequestHeader set X-Forwarded-Host "yoursite.com"
RequestHeader set X-Forwarded-Proto "https"
# Required for domain verification
RequestHeader set X-Jamdesk-Forwarded-Host "yoursite.com"
</Location>
</VirtualHost>
Assurez-vous que les modules requis sont activés :
sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2Caddy
Caddy propose une configuration de proxy inverse simple avec HTTPS automatique :
yoursite.com {
# Your existing configuration...
handle /docs* {
reverse_proxy https://YOUR_SLUG.jamdesk.app {
header_up Host {upstream_hostport}
header_up X-Forwarded-Host {host}
# Required for domain verification
header_up X-Jamdesk-Forwarded-Host {host}
}
}
# Next.js static assets and Jamdesk assets
handle /_next/* {
reverse_proxy https://YOUR_SLUG.jamdesk.app {
header_up Host {upstream_hostport}
}
}
handle /_jd/* {
reverse_proxy https://YOUR_SLUG.jamdesk.app {
header_up Host {upstream_hostport}
}
}
# Handle other routes
handle {
# Your main site configuration
}
}
Rechargez Caddy après les modifications :
sudo systemctl reload caddyTraefik
Pour les utilisateurs de Traefik, configurez un routeur et un service :
http:
routers:
docs-router:
rule: "Host(`yoursite.com`) && (PathPrefix(`/docs`) || PathPrefix(`/_next`) || PathPrefix(`/_jd`))"
service: jamdesk-docs
middlewares:
- jamdesk-headers
tls: {}
middlewares:
jamdesk-headers:
headers:
customRequestHeaders:
# Required for domain verification
X-Jamdesk-Forwarded-Host: "yoursite.com"
services:
jamdesk-docs:
loadBalancer:
servers:
- url: "https://YOUR_SLUG.jamdesk.app"
passHostHeader: falseHAProxy
Pour HAProxy, ajoutez des règles backend et ACL :
frontend https
bind *:443 ssl crt /etc/ssl/certs/yoursite.pem
# Route /docs and assets to Jamdesk backend
acl is_docs path_beg /docs
acl is_next path_beg /_next
acl is_jd path_beg /_jd
use_backend jamdesk_docs if is_docs or is_next or is_jd
# Default backend for other requests
default_backend main_site
backend jamdesk_docs
server jamdesk YOUR_SLUG.jamdesk.app:443 ssl verify none
http-request set-header Host YOUR_SLUG.jamdesk.app
http-request set-header X-Forwarded-Host %[req.hdr(host)]
# Required for domain verification
http-request set-header X-Jamdesk-Forwarded-Host %[req.hdr(host)]
Redirigez aussi vos fichiers racine
robots.txt, sitemap.xml, llms.txt et llms-full.txt sont servis depuis la racine du domaine, et non depuis /docs — un proxy qui ne redirige que /docs, /_next et /_jd laisse ces fichiers servis par votre propre site (ou pas servis du tout), ce qui casse la découverte par les agents IA et vous coûte du référencement, indépendamment du reste de cette page.
Ajoutez le même modèle de bloc location/route que celui utilisé pour /docs ci-dessus, pour chacun de ces quatre chemins. Pour nginx :
location = /robots.txt {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
location = /sitemap.xml {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
location = /llms.txt {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
location = /llms-full.txt {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
Ces mêmes quatre blocs — mêmes en-têtes, même upstream — s'appliquent à Apache, Caddy, Traefik et HAProxy : copiez le bloc /docs que vous utilisez ci-dessus et répétez-le une fois par chemin.
Ne redirigez ces fichiers que si Jamdesk possède la racine de votre domaine. Si votre site principal sert déjà son propre robots.txt ou sitemap.xml, fusionnez les deux au lieu d'écraser l'un par l'autre.
En-têtes requis
Quel que soit le proxy que vous utilisez, assurez-vous que ces en-têtes sont définis :
| Header | Valeur | Objectif |
|---|---|---|
Host | YOUR_SLUG.jamdesk.app | Identifie la requête auprès de Jamdesk |
X-Forwarded-Host | Votre domaine | Indique à Jamdesk quel domaine utiliser dans les URL |
X-Forwarded-Proto | https | Garantit la génération sécurisée des URL |
X-Jamdesk-Forwarded-Host | Votre domaine | Requis pour la vérification du domaine |
Marqueur de requête ?jd_proxy=1 | Ajouté à l'URL en amont | Alternative à l'en-tête, pour les outils qui ne peuvent que réécrire une URL et ne peuvent pas définir d'en-têtes de requête — voir Domaine personnalisé uniquement |
L'en-tête X-Jamdesk-Forwarded-Host (ou le marqueur ?jd_proxy=1) est requis, et s'en passer échoue silencieusement.
Les requêtes réussissent quand même — rien ne génère d'erreur, ce qui les rend justement faciles à manquer. Ce qui casse est plus subtil :
- Si vous n'avez pas enregistré de domaine personnalisé dans le dashboard, vos pages de documentation sont servies avec
<meta name="robots" content="noindex">, et les URL canoniques, Open Graph et de sitemap pointent toutes versYOUR_SLUG.jamdesk.appau lieu de votre domaine. Les moteurs de recherche n'indexeront jamais votre documentation. - Si vous avez enregistré un domaine personnalisé, Jamdesk se rabat sur le domaine enregistré, donc vos URL restent correctes — mais il ne peut toujours pas distinguer le trafic du proxy du trafic direct vers votre sous-domaine
*.jamdesk.app, et la vérification préalable Domaine personnalisé uniquement échouera.
Un 403 est le problème inverse : l'en-tête est présent, mais désigne un domaine qui n'est pas enregistré et actif pour ce projet.
La configuration du proxy est une configuration ponctuelle. Si vous changez plus tard votre domaine personnalisé ou votre configuration dans le dashboard Jamdesk, le proxy n'a pas besoin d'être mis à jour - toutes les décisions de routage sont prises côté serveur en fonction des paramètres de votre dashboard.
Dépannage
Vérifiez que le proxy peut atteindre YOUR_SLUG.jamdesk.app en HTTPS. Vérifiez les règles de pare-feu et la résolution DNS.
Activez SSL/TLS pour la connexion en amont. Pour nginx, ajoutez proxy_ssl_server_name on;. Pour Apache, activez SSLProxyEngine On.
Assurez-vous que l'en-tête X-Forwarded-Host est correctement défini. Cela indique à Jamdesk quel domaine utiliser pour les URL des ressources et les liens internes.
Vérifiez que votre proxy ne suit pas les redirections. Le proxy doit transmettre la réponse telle quelle, sans gestion supplémentaire des redirections.
Si vous voyez « Domain is not authorized to serve this content » :
- Vérifiez que votre domaine est enregistré dans le dashboard Jamdesk
- Effectuez la vérification DNS (enregistrement TXT) pour votre domaine
- Assurez-vous que l'en-tête
X-Jamdesk-Forwarded-Hostest défini dans votre configuration de proxy - Vérifiez que votre domaine correspond au bon projet
Le domaine doit être vérifié avant que le proxy puisse servir la documentation.
Preflight récupère /_jd/preflight sur votre domaine en production et vérifie ce qui est réellement parvenu à Jamdesk. S'il signale que votre proxy « ne s'identifie pas », une requête a atteint Jamdesk mais sans l'en-tête ni le marqueur — revérifiez la ligne X-Jamdesk-Forwarded-Host dans chaque bloc location/route ci-dessus. Consultez Domaine personnalisé uniquement pour la signification de chaque message de preflight.