Proxy inverse
Servez votre documentation sur /docs avec nginx, Apache, Caddy, Traefik ou HAProxy. 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 transfère 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)
nginx
Ajoutez un bloc location pour transférer 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 réel.
La gestion du chemin est importante. L'URL proxy_pass n'a pas de chemin final, donc nginx conserve le chemin de requête d'origine. Une requête vers /docs/page est transféré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 transférer 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 de backend et d'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)]
Transférez aussi vos fichiers racine
robots.txt, sitemap.xml, llms.txt et llms-full.txt sont servis depuis la racine du domaine, pas sous /docs — un proxy qui ne transfère que /docs, /_next et /_jd laisse ces fichiers servis par votre propre site (ou pas servis du tout), ce qui compromet la découverte par les agents IA et nuit à votre SEO, 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;
}
Les quatre mêmes 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 transférez 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'en remplacer 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 :
| En-tête | 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 URLs |
X-Forwarded-Proto | https | Garantit une génération d'URL sécurisée |
X-Jamdesk-Forwarded-Host | Votre domaine | Requis pour la vérification du domaine |
Marqueur de requête ?jd_proxy=1 | Ajouté à l'URL upstream | Alternative à l'en-tête, pour les outils qui ne peuvent que réécrire une URL sans pouvoir 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 l'omettre é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 URLs canoniques, Open Graph et 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 URLs restent correctes — mais il ne peut toujours pas distinguer le trafic 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 ni enregistré ni actif pour ce projet.
La configuration du proxy est une configuration unique. Si vous modifiez ultérieurement 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 via HTTPS. Vérifiez les règles de pare-feu et la résolution DNS.
Activez SSL/TLS pour la connexion upstream. 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 URLs des ressources et les liens internes.
Vérifiez que votre proxy ne suit pas les redirections. Le proxy doit transférer la réponse telle quelle, sans traitement supplémentaire des redirections.
Si vous voyez le message « 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) de votre domaine
- Assurez-vous que l'en-tête
X-Jamdesk-Forwarded-Hostest défini dans la configuration de votre proxy - Vérifiez que votre domaine correspond au bon projet
Le domaine doit être vérifié avant que le proxy puisse servir la documentation.
La vérification préalable récupère /_jd/preflight sur votre domaine en production et vérifie ce qui a réellement atteint Jamdesk. Si elle 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 connaître la signification de chaque message de vérification préalable.