Jamdesk Documentation logo

Reverse-Proxy

Stellen Sie Ihre Dokumentation unter /docs mit nginx, Apache, Caddy, Traefik oder HAProxy bereit. Mit getesteten Konfigurationsbeispielen für jeden Reverse Proxy.

Fügen Sie in nginx, Apache, Caddy, Traefik oder HAProxy einen location-/route-Block hinzu, der /docs-Traffic an Ihre Jamdesk-Subdomain weiterleitet.

Voraussetzungen

  • Zugriff auf Ihre Webserver-Konfiguration
  • Ihre Jamdesk-Subdomain (zu finden in den Dashboard-Einstellungen)

Verwenden Sie einen eigenen Unterpfad statt des Standardpfads /docs? Ersetzen Sie /docs in jedem location-/route-Block unten durch Ihren Unterpfad. Aktualisieren Sie die Konfiguration erneut, nachdem Sie den Unterpfad im Dashboard geändert haben.

nginx

Fügen Sie einen location-Block hinzu, um /docs-Anfragen an Jamdesk weiterzuleiten:

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;
    }

}

Ersetzen Sie YOUR_SLUG durch Ihre Jamdesk-Subdomain.

Die Pfadbehandlung ist wichtig. Die proxy_pass-URL hat keinen nachgestellten Pfad. nginx behält den ursprünglichen Anfragepfad bei. Eine Anfrage an /docs/page wird an jamdesk.app/docs/page weitergeleitet. Ein abschließender Schrägstrich (proxy_pass https://...jamdesk.app/) entfernt das Präfix /docs. Belassen Sie es genau wie oben gezeigt.

nginx neu laden:

sudo nginx -t && sudo systemctl reload nginx

Apache

Verwenden Sie mod_proxy, um /docs-Anfragen an Jamdesk weiterzuleiten:

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>

Aktivieren Sie die benötigten Module:

sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2

Caddy

Caddy richtet HTTPS selbstständig ein. Fügen Sie diese handle-Blöcke hinzu:

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

Caddy nach Änderungen neu laden:

sudo systemctl reload caddy

Traefik

Konfigurieren Sie einen Traefik-Router und -Service:

traefik.yml
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: false

HAProxy

Fügen Sie das HAProxy-Backend und die ACL-Regeln hinzu:

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

Root-Dateien ebenfalls weiterleiten

robots.txt, sitemap.xml, llms.txt und llms-full.txt liegen auf der Domain-Root, nicht unter /docs. Ein Proxy, der nur /docs, /_next und /_jd weiterleitet, lässt diese bei Ihrer eigenen Seite oder lässt sie fehlen. Das beeinträchtigt die Erkennung durch KI-Agenten und Ihre SEO.

Fügen Sie für jeden dieser vier Pfade das location-/route-Muster hinzu, das Sie für /docs verwendet haben. Für nginx:

nginx.conf
    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;
    }

Für Apache, Caddy, Traefik oder HAProxy kopieren Sie Ihren /docs-Block und wiederholen ihn für jeden Pfad. Behalten Sie dieselben Header und dasselbe Upstream bei.

Leiten Sie diese nur weiter, wenn Jamdesk Ihre Domain-Root verwaltet. Wenn Ihre Hauptseite bereits eigene robots.txt- oder sitemap.xml-Dateien ausliefert, führen Sie beide zusammen, statt eine durch die andere zu überschreiben.

Erforderliche Header

Setzen Sie diese Header auf jedem Proxy:

HeaderWertZweck
HostYOUR_SLUG.jamdesk.appIdentifiziert die Anfrage für Jamdesk
X-Forwarded-HostIhre DomainTeilt Jamdesk mit, welche Domain in URLs verwendet werden soll
X-Forwarded-ProtohttpsStellt die Generierung sicherer URLs sicher
X-Jamdesk-Forwarded-HostIhre DomainErforderlich für die Domain-Verifizierung
?jd_proxy=1-Query-MarkerAn die Upstream-URL angehängtAlternative zum Header, für Tools, die nur eine URL umschreiben, aber keine Request-Header setzen können. Siehe Nur eigene Domain

Der Header X-Jamdesk-Forwarded-Host (oder der Marker ?jd_proxy=1) ist erforderlich. Wenn beides fehlt, schlägt es stillschweigend fehl.

Anfragen gelingen weiterhin, und es gibt keine Fehlermeldung. Folgendes geht kaputt:

  • Keine eigene Domain im Dashboard registriert: Jamdesk liefert Ihre Seiten mit <meta name="robots" content="noindex"> aus. Canonical-, Open-Graph- und Sitemap-URLs verweisen auf YOUR_SLUG.jamdesk.app statt auf Ihre Domain. Suchmaschinen indexieren Ihre Dokumentation dann nie.
  • Eigene Domain registriert: Jamdesk greift auf die hinterlegte Domain zurück, und Ihre URLs bleiben korrekt. Jamdesk kann Proxy-Traffic trotzdem nicht vom direkten Traffic auf Ihre *.jamdesk.app-Subdomain unterscheiden. Die Preflight-Prüfung Nur eigene Domain schlägt fehl.

Ein 403 bedeutet, dass der Header vorhanden ist, aber eine Domain nennt, die für dieses Projekt nicht registriert und aktiv ist.

Die Proxy-Konfiguration ist eine einmalige Einrichtung. Änderungen an Ihrer eigenen Domain oder der Konfiguration im Jamdesk-Dashboard erfordern kein Proxy-Update. Jamdesk trifft Routing-Entscheidungen serverseitig auf Basis Ihrer Dashboard-Einstellungen.

Fehlerbehebung

Prüfen Sie, ob der Proxy YOUR_SLUG.jamdesk.app über HTTPS erreichen kann. Kontrollieren Sie Firewall-Regeln und DNS-Auflösung.

Aktivieren Sie SSL/TLS für die Upstream-Verbindung. Für nginx fügen Sie proxy_ssl_server_name on; hinzu. Für Apache aktivieren Sie SSLProxyEngine On.

Prüfen Sie den Header X-Forwarded-Host. Jamdesk verwendet ihn, um Asset-URLs und interne Links zu erstellen.

Prüfen Sie, ob Ihr Proxy keinen Redirects folgt. Er sollte die Antwort unverändert weiterleiten.

Sehen Sie „Domain is not authorized to serve this content“? Gehen Sie diese Punkte durch:

  1. Prüfen Sie, ob Ihre Domain im Jamdesk-Dashboard registriert ist
  2. Schließen Sie die DNS-Verifizierung (TXT-Eintrag) für Ihre Domain ab
  3. Setzen Sie den Header X-Jamdesk-Forwarded-Host in Ihrer Proxy-Konfiguration
  4. Prüfen Sie, ob Ihre Domain dem richtigen Projekt zugeordnet ist

Die Domain muss verifiziert sein, bevor der Proxy die Dokumentation ausliefern kann.

Preflight ruft /_jd/preflight auf Ihrer Live-Domain ab und prüft, was Jamdesk erreicht hat. „Identifiziert sich nicht“ bedeutet, dass eine Anfrage Jamdesk ohne den Header oder den Marker erreicht hat. Prüfen Sie die Zeile X-Jamdesk-Forwarded-Host in jedem location-/route-Block oben erneut. Was die einzelnen Preflight-Meldungen bedeuten, steht unter Nur eigene Domain.

Wie geht es weiter?

Nur eigene Domain

Verhindern, dass Ihre Subdomain direkt antwortet

Eigene Domains

DNS verifizieren und Probleme beheben

Unterpfad-Hosting

Dokumentation unter /docs bereitstellen