Jamdesk Documentation logo

Reverse Proxy

Serva la tua documentazione su /docs con nginx, Apache, Caddy, Traefik o HAProxy. Include snippet di configurazione testati per ogni reverse proxy.

Aggiungi un blocco location/route a nginx, Apache, Caddy, Traefik o HAProxy che inoltri il traffico /docs al tuo sottodominio Jamdesk.

Prerequisiti

  • Accesso alla configurazione del tuo web server
  • Il tuo sottodominio Jamdesk (disponibile nelle impostazioni della dashboard)

Usi un sottopercorso personalizzato invece del /docs predefinito? Sostituisci /docs con il tuo sottopercorso in ogni blocco location/route qui sotto. Aggiorna di nuovo la configurazione dopo aver rinominato il sottopercorso nella dashboard.

nginx

Aggiungi un blocco location per inoltrare le richieste /docs a 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;
    }

}

Sostituisci YOUR_SLUG con il tuo sottodominio Jamdesk.

La gestione del percorso è importante. L'URL di proxy_pass non ha un percorso finale. nginx mantiene il percorso originale della richiesta. Una richiesta a /docs/page viene inoltrata a jamdesk.app/docs/page. Uno slash finale (proxy_pass https://...jamdesk.app/) rimuove il prefisso /docs. Mantienilo esattamente come mostrato sopra.

Ricarica nginx:

sudo nginx -t && sudo systemctl reload nginx

Apache

Usa mod_proxy per inoltrare le richieste /docs a 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>

Abilita i moduli richiesti:

sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2

Caddy

Caddy configura HTTPS da solo. Aggiungi questi blocchi handle:

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

Ricarica Caddy dopo le modifiche:

sudo systemctl reload caddy

Traefik

Configura un router e un service Traefik:

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

Aggiungi il backend e le regole ACL di HAProxy:

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

Inoltra anche i file nella root

robots.txt, sitemap.xml, llms.txt e llms-full.txt si trovano nella radice del dominio, non sotto /docs. Un proxy che inoltra solo /docs, /_next e /_jd lascia questi file al tuo sito, oppure li fa mancare. Questo compromette la scoperta da parte degli agenti AI e la SEO.

Aggiungi il pattern location/route usato per /docs per ciascuno di questi quattro percorsi. Per 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;
    }

Per Apache, Caddy, Traefik o HAProxy, copia il tuo blocco /docs e ripetilo una volta per ogni percorso. Mantieni gli stessi header e lo stesso upstream.

Inoltra questi file solo se Jamdesk gestisce la radice del tuo dominio. Se il tuo sito principale serve già il proprio robots.txt o sitemap.xml, unisci i contenuti invece di sovrascrivere l'uno con l'altro.

Header richiesti

Imposta questi header su qualsiasi proxy:

HeaderValoreScopo
HostYOUR_SLUG.jamdesk.appIdentifica la richiesta per Jamdesk
X-Forwarded-HostIl tuo dominioIndica a Jamdesk quale dominio usare negli URL
X-Forwarded-ProtohttpsGarantisce la generazione di URL sicuri
X-Jamdesk-Forwarded-HostIl tuo dominioRichiesto per la verifica del dominio
Marcatore di query ?jd_proxy=1Aggiunto all'URL upstreamAlternativa all'header, per gli strumenti che possono solo riscrivere un URL e non impostare header di richiesta. Vedi Solo dominio personalizzato

L'header X-Jamdesk-Forwarded-Host (o il marcatore ?jd_proxy=1) è obbligatorio. Ometterli entrambi causa un errore silenzioso.

Le richieste continuano a riuscire e non viene segnalato alcun errore. Ecco cosa si rompe:

  • Nessun dominio personalizzato registrato nella dashboard: Jamdesk serve le tue pagine con <meta name="robots" content="noindex">. Gli URL canonici, Open Graph e della sitemap puntano a YOUR_SLUG.jamdesk.app invece che al tuo dominio. I motori di ricerca non indicizzeranno mai la tua documentazione.
  • Dominio personalizzato registrato: Jamdesk usa il dominio registrato e i tuoi URL restano corretti. Jamdesk però non riesce a distinguere il traffico proxy da quello diretto verso il tuo sottodominio *.jamdesk.app. Il controllo preliminare Solo dominio personalizzato fallirà.

Un 403 significa che l'header è presente ma indica un dominio non registrato e attivo per questo progetto.

La configurazione del proxy è un setup una tantum. Modificare il dominio personalizzato o la configurazione nella dashboard di Jamdesk non richiede alcun aggiornamento del proxy. Jamdesk prende le decisioni di routing lato server in base alle impostazioni della tua dashboard.

Risoluzione dei problemi

Verifica che il proxy riesca a raggiungere YOUR_SLUG.jamdesk.app tramite HTTPS. Controlla le regole del firewall e la risoluzione DNS.

Abilita SSL/TLS per la connessione upstream. Per nginx, aggiungi proxy_ssl_server_name on;. Per Apache, abilita SSLProxyEngine On.

Controlla l'header X-Forwarded-Host. Jamdesk lo usa per costruire gli URL degli asset e dei link interni.

Verifica che il proxy non segua i redirect. Dovrebbe inoltrare la risposta così com'è.

Visualizzi "Domain is not authorized to serve this content"? Segui questi controlli:

  1. Verifica che il tuo dominio sia registrato nella dashboard di Jamdesk
  2. Completa la verifica DNS (record TXT) per il tuo dominio
  3. Imposta l'header X-Jamdesk-Forwarded-Host nella configurazione del proxy
  4. Controlla che il tuo dominio sia associato al progetto corretto

Il dominio deve essere verificato prima che il proxy possa servire la documentazione.

Il controllo preliminare recupera /_jd/preflight sul tuo dominio attivo e verifica cosa è arrivato a Jamdesk. "Non si identifica" significa che una richiesta è arrivata a Jamdesk senza l'header o il marcatore. Ricontrolla la riga X-Jamdesk-Forwarded-Host in ogni blocco location/route sopra. Vedi Solo dominio personalizzato per il significato di ogni messaggio del controllo preliminare.

Qual è il prossimo passo?

Solo dominio personalizzato

Impedisci al tuo sottodominio di rispondere direttamente

Domini personalizzati

Verifica il DNS e risolvi i problemi

Hosting su sottopercorso

Servi la documentazione su /docs