Jamdesk Documentation logo

Proxy reverso

Sirva sua documentação em /docs usando nginx, Apache, Caddy, Traefik ou HAProxy. Inclui trechos de configuração testados para cada proxy reverso.

Adicione um bloco location/route ao nginx, Apache, Caddy, Traefik ou HAProxy que encaminhe o tráfego de /docs para o seu subdomínio Jamdesk.

Pré-requisitos

  • Acesso à configuração do seu servidor web
  • Seu subdomínio Jamdesk (encontrado nas configurações do dashboard)

Usando um subcaminho personalizado em vez do /docs padrão? Substitua /docs pelo seu subcaminho em todos os blocos location/route abaixo. Atualize a configuração novamente depois de renomear o subcaminho no dashboard.

nginx

Adicione um bloco location para encaminhar requisições de /docs para o 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;
    }

}

Substitua YOUR_SLUG pelo seu subdomínio Jamdesk.

O tratamento do caminho importa. A URL do proxy_pass não tem caminho final. O nginx mantém o caminho original da requisição. Uma requisição para /docs/page é encaminhada para jamdesk.app/docs/page. Uma barra final (proxy_pass https://...jamdesk.app/) remove o prefixo /docs. Mantenha exatamente como mostrado acima.

Recarregue o nginx:

sudo nginx -t && sudo systemctl reload nginx

Apache

Use o mod_proxy para encaminhar requisições de /docs para o 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>

Ative os módulos necessários:

sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2

Caddy

Caddy configura HTTPS sozinho. Adicione estes blocos 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
    }
}

Recarregue o Caddy após as alterações:

sudo systemctl reload caddy

Traefik

Configure um router e um service do 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

Adicione o backend e as regras ACL do 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)]

Encaminhe também os arquivos da raiz

robots.txt, sitemap.xml, llms.txt e llms-full.txt ficam na raiz do domínio, não em /docs. Um proxy que encaminha apenas /docs, /_next e /_jd deixa esses arquivos com o seu próprio site, ou faltando. Isso quebra a descoberta por agentes de IA e prejudica o seu SEO.

Adicione o padrão de location/route que você usou para /docs para cada um desses quatro caminhos. Para 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;
    }

Para Apache, Caddy, Traefik ou HAProxy, copie o seu bloco de /docs e repita-o uma vez para cada caminho. Mantenha os mesmos headers e o mesmo upstream.

Encaminhe esses arquivos somente se a Jamdesk for responsável pela raiz do seu domínio. Se o seu site principal já serve seu próprio robots.txt ou sitemap.xml, combine os dois em vez de sobrescrever um com o outro.

Cabeçalhos obrigatórios

Defina estes headers em qualquer proxy:

HeaderValorFinalidade
HostYOUR_SLUG.jamdesk.appIdentifica a requisição para o Jamdesk
X-Forwarded-HostSeu domínioInforma ao Jamdesk qual domínio usar nas URLs
X-Forwarded-ProtohttpsGarante a geração de URLs seguras
X-Jamdesk-Forwarded-HostSeu domínioObrigatório para a verificação de domínio
Marcador de query ?jd_proxy=1Anexado à URL upstreamAlternativa ao header, para ferramentas que só conseguem reescrever uma URL e não podem definir headers de requisição. Veja Somente domínio personalizado

O header X-Jamdesk-Forwarded-Host (ou o marcador ?jd_proxy=1) é obrigatório. Omiti-los falha silenciosamente.

As requisições ainda têm sucesso e nada gera erro. Veja o que quebra:

  • Nenhum domínio personalizado registrado no dashboard: o Jamdesk serve suas páginas com <meta name="robots" content="noindex">. As URLs canônicas, Open Graph e do sitemap apontam para YOUR_SLUG.jamdesk.app em vez do seu domínio. Os mecanismos de busca nunca indexarão sua documentação.
  • Domínio personalizado registrado: o Jamdesk usa o domínio cadastrado, e suas URLs continuam corretas. Mesmo assim, o Jamdesk não consegue distinguir o tráfego do proxy do tráfego direto para o seu subdomínio *.jamdesk.app. A verificação preliminar Somente domínio personalizado vai falhar.

Um 403 significa que o header está presente, mas indica um domínio que não está registrado e ativo para este projeto.

A configuração do proxy é uma configuração única. Alterar seu domínio personalizado ou a configuração no dashboard do Jamdesk não exige atualização do proxy. O Jamdesk toma as decisões de roteamento do lado do servidor, a partir das configurações do seu dashboard.

Solução de problemas

Verifique se o proxy consegue alcançar YOUR_SLUG.jamdesk.app via HTTPS. Confira as regras de firewall e a resolução de DNS.

Ative SSL/TLS para a conexão upstream. No nginx, adicione proxy_ssl_server_name on;. No Apache, ative SSLProxyEngine On.

Verifique o header X-Forwarded-Host. O Jamdesk o usa para construir URLs de assets e links internos.

Verifique se o seu proxy não está seguindo redirecionamentos. Ele deve encaminhar a resposta exatamente como recebida.

Está vendo "Domain is not authorized to serve this content"? Siga estas verificações:

  1. Confirme que seu domínio está registrado no dashboard do Jamdesk
  2. Conclua a verificação de DNS (registro TXT) do seu domínio
  3. Defina o header X-Jamdesk-Forwarded-Host na configuração do proxy
  4. Confirme que seu domínio aponta para o projeto correto

O domínio precisa estar verificado antes que o proxy possa servir a documentação.

A verificação preliminar busca /_jd/preflight no seu domínio em produção e verifica o que chegou ao Jamdesk. "Não se identifica" significa que uma requisição chegou ao Jamdesk sem o header ou o marcador. Revise a linha X-Jamdesk-Forwarded-Host em cada bloco location/route acima. Veja Somente domínio personalizado para o significado de cada mensagem da verificação.

O que vem a seguir?

Somente domínio personalizado

Impeça que seu subdomínio responda diretamente

Domínios personalizados

Verifique o DNS e solucione problemas

Hospedagem em subcaminho

Sirva a documentação em /docs