Como fazer self-host do Stirling PDF em 2026: uploads, OCR e segurança de login

Há duas versões de “executar o Stirling PDF”: existe um container ou o serviço conclui seu trabalho de verdade. Apenas a segunda importa. Aqui, a validação consiste em mesclar dois PDFs, fazer OCR de uma página digitalizada, comprimir o resultado e verificar o comportamento de upload e download pelo proxy público.

O Stirling PDF atende a esse objetivo: uma interface web e uma API para operações comuns em PDF. O deployment precisa preservar os componentes por trás desse comportamento; uma porta, um volume e um certificado são entradas, não o resultado.

Configurações do container que vale a pena revisar

O primeiro container deve ser fácil de excluir e recriar. Mantenha os dados fora da camada gravável, faça o bind da porta 8080 apenas onde o proxy possa alcançá-la e passe a configuração em runtime.

docker run -d \
  --name stirling-pdf \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v stirling-pdf-data:/configs \
  -e SECURITY_ENABLELOGIN=true \
  stirlingtools/stirling-pdf:latest

Fixe a versão da image após o teste inicial. Leia o erro mais antigo da inicialização em vez da mensagem final de restart, verifique cada mount com docker inspect e acompanhe os logs enquanto você mescla dois PDFs, faz OCR de uma página digitalizada, comprime o resultado e verifica o comportamento de upload e download pelo proxy público. Essa sequência diferencia um comando de image incorreto de um problema de dependência ou permissão.

Defina primeiro o que significa sucesso para o Stirling PDF

Separe quatro aspectos do Stirling PDF: ingress, o listener na porta 8080, o estado persistente e os serviços de suporte ou a capacidade local. O requisito de runtime local é composto por dados opcionais de idiomas para OCR e espaço em disco temporário suficiente para jobs grandes. Registre isso junto da image e da porta para que um host substituto receba a mesma capacidade local.

Execute a transação conhecida — mesclar dois PDFs, fazer OCR de uma página digitalizada, comprimir o resultado e verificar o comportamento de upload e download pelo proxy público — antes de considerar essa separação concluída. Meça o espaço temporário em disco, os pacotes de idiomas para OCR, a memória da JVM e a quantidade de jobs de conversão simultâneos, e mantenha o resultado junto do registro do deployment. Isso fornece tanto um critério de aceitação quanto a primeira baseline de capacidade.

Proteja o Stirling PDF após o bootstrap

O risco de segurança específico da aplicação é deixar a segurança desativada em um serviço público de processamento de documentos. A resposta operacional é habilitar o login em uma instância exposta à internet e evitar manter documentos enviados por mais tempo do que o necessário para o job. Conclua o bootstrap por uma rota restrita e remova imediatamente o acesso temporário de configuração.

SECURITY_ENABLELOGIN controla o comportamento, não a confidencialidade; valide seu tipo e valor e armazene as credenciais reais do Stirling PDF separadamente. Conceda ao processo do Stirling PDF apenas os mounts e as rotas de dependência documentados; evite acesso à raiz do host e ao Docker socket. Registre falhas de autenticação e erros de configuração, mas remova tokens, connection strings e conteúdo de usuários dos logs.

Dê ao Stirling PDF um único endereço canônico

O browser, o cliente da API e o Stirling PDF precisam concordar sobre uma única origem. Para garantir isso, configure a origem HTTPS pública e os limites de upload do proxy. Preserve o host e o protocolo originais, mantendo a porta 8080 indisponível como um endereço público concorrente.

O guia de troubleshooting de site indisponível ajuda a diferenciar uma rota inacessível de uma aplicação que está respondendo. Essa distinção é importante aqui: os uploads ultrapassam o limite do proxy ou o container não consegue gravar arquivos temporários. Apenas o primeiro caso é corrigido com mudanças no ingress; o segundo exige a análise dos logs, do estado ou da carga de trabalho do Stirling PDF.

Separe containers substituíveis de dados duráveis

O conjunto de recuperação persistente é composto pela configuração, pelos arquivos personalizados e por quaisquer dados de OCR que você tenha instalado deliberadamente. Monte /configs antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Um volume protege os dados contra a substituição do container, mas não contra a perda do host, a exclusão acidental ou a corrupção no nível da aplicação.

Faça backups que entendam a fonte dos dados: use logical dumps para bancos de dados ativos quando necessário e copie arquivos apenas a partir de um estado consistente. Mantenha uma cópia criptografada fora do host do Stirling PDF. O critério de aceitação de um restore deve ser específico — a configuração e os assets de OCR precisam retornar, e um documento de teste fixo deve produzir um resultado aceitável e legível. O guia de backup testado com restore explica por que o sucesso do job, sozinho, é insuficiente.

Evidências a coletar antes de colocar o Stirling PDF em produção

Para o Stirling PDF, defina uma transação conhecida como válida antes do lançamento: mesclar dois PDFs, fazer OCR de uma página digitalizada, comprimir o resultado e verificar o comportamento de upload e download pelo proxy público. Coloque os pré-requisitos, a resposta esperada e as etapas de limpeza no controle de versão, sem valores secretos. Fixe a image usada para estabelecer essa referência.

Use a transação para validar uma substituição e um restore independente. O serviço restaurado só será aceitável quando a configuração e os assets de OCR retornarem e um documento de teste fixo produzir um resultado aceitável e legível. Ao mesmo tempo, observe o espaço temporário em disco, os pacotes de idiomas para OCR, a memória da JVM e os jobs de conversão simultâneos, transformando a parte mais lenta ou mais limitada em um alerta de nível de serviço.

O gate também precisa de um caso negativo: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a esta fronteira: os uploads ultrapassam o limite do proxy ou o container não consegue gravar arquivos temporários. Confirme que o Stirling PDF produz um erro acionável sem perder dados, restaure a condição válida e repita a transação conhecida como válida. Manter os dois resultados evita que um health endpoint superficial se torne a única evidência em produção.

Opere o Stirling PDF em torno do gargalo real

Observe o trabalho realizado pelo Stirling PDF: espaço temporário em disco, pacotes de idiomas para OCR, memória da JVM e jobs de conversão simultâneos. Defina limites com margem para esse trabalho e evite uma liveness probe que concorra com ele. A verificação operacional ainda deve tentar mesclar dois PDFs, fazer OCR de uma página digitalizada, comprimir o resultado e verificar o comportamento de upload e download pelo proxy público em uma rotina programada.

Nas atualizações, lembre-se de que os dados de OCR instalados, a configuração personalizada e as definições de segurança devem ser comparados antes de um upgrade da image. Faça o deployment da candidata sobre uma cópia recuperada e repita o teste conhecido. Se os uploads ultrapassarem o limite do proxy ou o container não conseguir gravar arquivos temporários, use os logs de runtime e a requisição de rede real para descobrir qual suposição mudou.

Faça o deployment do Stirling PDF no Dockup sem perder seus limites

O Dockup elimina o trabalho manual de reverse proxy e lifecycle em torno do Stirling PDF. O serviço recebe uma rota HTTPS estável para a porta 8080, configuração injetada e armazenamento persistente durante as substituições. Um servidor do cliente conectado segue o mesmo modelo do compute hospedado no Dockup.

Após o lançamento, cumpra o contrato da aplicação: configure a origem HTTPS pública e os limites de upload do proxy, confirme o requisito local — dados opcionais de idiomas para OCR e espaço temporário em disco suficiente para jobs grandes — e execute esta validação: mescle dois PDFs, faça OCR de uma página digitalizada, comprima o resultado e verifique o comportamento de upload e download pelo proxy público. Isso mantém a experiência de um clique útil sem apagar os detalhes que tornam o Stirling PDF recuperável e seguro.

Perguntas frequentes

O que o Stirling PDF precisa para um deployment em produção?

Encaminhe o container do Stirling PDF na porta 8080 por meio de uma única origem HTTPS. O requisito de runtime local é composto por dados opcionais de idiomas para OCR e espaço temporário em disco suficiente para jobs grandes. Não considere o Stirling PDF pronto até conseguir mesclar dois PDFs, fazer OCR de uma página digitalizada, comprimir o resultado e verificar o comportamento de upload e download pelo proxy público.

Quais dados do Stirling PDF devem entrar no backup?

Mantenha /configs persistente e inclua a configuração, os arquivos personalizados e quaisquer dados de OCR instalados deliberadamente no mesmo manifesto de recuperação. Um restore limpo do Stirling PDF só será aprovado quando a configuração e os assets de OCR retornarem e um documento de teste fixo produzir um resultado aceitável e legível.

O Stirling PDF exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Stirling PDF e mantenha a porta 8080 na rota interna. Aplique corretamente a configuração do Stirling PDF: defina a origem HTTPS pública e os limites de upload do proxy. Para o Stirling PDF, o HTTPS protege credenciais ou conteúdo de usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Stirling PDF?

Restaure o estado atual do Stirling PDF em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial, pois os dados de OCR instalados, a configuração personalizada e as definições de segurança devem ser comparados antes de um upgrade da image. Mantenha a image anterior do Stirling PDF até entender os limites de migração de dados e rollback.