As fontes Mintlify ficam em /opt/server/docs/. O build estático é servido pelo container docs (nginx:alpine) em /opt/server/infra/docs/, exposto via NPM. Build é manual — você roda o script quando quer publicar.

​
Setup inicial

1

Garantir que o mint CLI está instalado

O build.sh chama mint export. Instalar global se ainda não tiver:
npm i -g mintlify
mint --version    # confirmar que rodou
2

Primeiro build

cd /opt/server/infra/docs
./build.sh
Gera site/ com ~50MB de HTML + chunks JS/CSS. Roda mint export por baixo, extrai o zip, e remove os launchers air-gap (serve.js, Start Docs.bat, Start Docs.command) que vêm no export mas não servem pro nginx.
3

Subir o container

docker compose up -d
Container docs (nginx:alpine) entra na server_net, sem expor porta no host — só o NPM enxerga.
4

Criar Proxy Host no NPM

Em https://npm.example.com → Hosts → Proxy Hosts → Add:Details:
  • Domain: docs.example.com
  • Scheme: http
  • Forward Hostname: docs
  • Forward Port: 80
  • Block Common Exploits: ligado
  • Websockets: desligado (não usa)
SSL:
  • Request new SSL Certificate
  • Force SSL + HTTP/2
Antes de salvar, garantir que docs.example.com resolve via DNS pro IP do servidor (CNAME pra example.com se já tiver A no apex).

​
Republicar (depois de editar .mdx)

cd /opt/server/infra/docs
./build.sh
Pronto. Nginx serve direto do FS — não precisa restart do container.

​
O que o build.sh faz

  1. cd /opt/server/docs && mint export --output /tmp/<random>.zip
  2. rm -rf site/ e recria
  3. Extrai o zip em site/ (via python3 -m zipfile)
  4. Remove serve.js + Start Docs.bat + Start Docs.command (modo air-gap, não usado aqui)
Variável opcional DOCS_SOURCE se quiser apontar pra outra pasta de fontes.

​
nginx.conf — refinos aplicados

ComportamentoPor quê
gzip onJS do Next dá ~13MB descompactado, gzip derruba pra ~3-4MB
Cache-Control: ..., immutable em /_next/static/Assets têm hash no nome — nunca mudam até o próximo build
Cache-Control: max-age=300 em *.htmlHTML pode mudar a cada deploy; cache curto pra propagar rápido
try_files $uri $uri/ $uri.html =404Mintlify gera /architecture/index.html. Sem isso, URLs sem barra final dariam 404.

​
Validar manualmente

Sem precisar do NPM (rede interna): 
docker run --rm --network server_net curlimages/curl -sI http://docs/
docker run --rm --network server_net curlimages/curl -sI http://docs/operations/backups/
Esperado: 200 OK com Cache-Control correto pra cada tipo.

​
Limitações conhecidas

  • Build manual. Esquecer de rodar ./build.sh depois de editar = .mdx novo não aparece em produção. Se virar problema, automatizar via git hook (post-commit em /opt/server/.git/hooks/).
  • Não tem busca server-side. O Mintlify SaaS oferece busca indexada; o export estático tem só client-side básico.
  • Sem analytics nativo. Pode adicionar tag de analytics no docs.json (integrations) antes do build, ou nada.