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 router les requêtes /docs vers Jamdesk :

nginx.conf

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 des chemins est importante. L'URL proxy_pass n'a pas de chemin final, donc nginx préserve le chemin de requête original. Une requête vers /docs/page est proxifiée vers jamdesk.app/docs/page. Si vous ajoutez un slash final (proxy_pass https://...jamdesk.app/), le préfixe /docs sera supprimé. Conservez la configuration exactement comme indiqué ci-dessus.

Après avoir mis à jour votre configuration, rechargez nginx :

sudo nginx -t && sudo systemctl reload nginx

Apache

Utilisez mod_proxy pour transférer les requêtes /docs vers Jamdesk :

httpd.conf or .htaccess

<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 apache2

Caddy

Caddy propose une configuration simple de reverse proxy avec HTTPS automatique :

Caddyfile

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 caddy

Traefik

Pour les utilisateurs de Traefik, configurez un routeur et un service :

traefik.yml

http:
  routers:
    docs-router:
      rule: "Host(`yoursite.com`) && (PathPrefix(`/docs`) || PathPrefix(`/_next`) || PathPrefix(`/_jd`))"
      service: jamdesk-docs
      tls: {}

  services:
    jamdesk-docs:
      loadBalancer:
        servers:
          - url: "https://YOUR_SLUG.jamdesk.app"
        passHostHeader: false

HAProxy

Pour HAProxy, ajoutez des règles backend et ACL :

haproxy.cfg

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

En-têtes requis

Quel que soit le proxy utilisé, 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 URL
`X-Forwarded-Proto`	`https`	Garantit la génération d'URL sécurisées
`X-Jamdesk-Forwarded-Host`	Votre domaine	Requis pour la vérification du domaine

L'en-tête X-Jamdesk-Forwarded-Host est obligatoire. Il permet :

La vérification du domaine (votre domaine doit être enregistré dans le dashboard)
La génération correcte des URL pour les liens et les ressources
La configuration appropriée depuis les paramètres de votre dashboard

Sans cet en-tête, les requêtes seront rejetées avec une erreur 403.

La configuration du proxy est une opération 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. Contrôlez 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 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 traitement 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-Host est défini dans la configuration de votre proxy
Vérifiez que votre domaine est associé au bon projet

Le domaine doit être vérifié avant que le proxy puisse servir la documentation.

Étapes suivantes

Vue d'ensemble du déploiement

Comparer les options d'hébergement

Hébergement sur sous-chemin

Servir la documentation sur /docs

Domaines personnalisés

Vérifier DNS et résoudre les problèmes