blog
Infraestrutura web

Java em cPanel: publicar um .war no Tomcat em container

O caminho documentado pelo cPanel para Java é Tomcat em container com proxy reverso na frente. Com loja.war implantado, GET / no backend devolve 404, e esse 404 é boa notícia.

JR · · 10 min de leitura · 2 tabelas · 10 blocos de código

Resposta curta: dá: o caminho documentado pelo cPanel para Java é o Tomcat via Containers, com a JVM rodando em container na conta e o Apache ou o LiteSpeed fazendo proxy reverso para a porta do conector HTTP e terminando o HTTPS na frente. O critério de sucesso é /loja/ responder 200.

Neste artigo
  1. O que existe de verdade em cPanel para Java
  2. A cadeia completa de uma requisição, do navegador ao servlet
  3. O 404 na raiz que prova que o Tomcat está vivo
  4. Do código de status ao elo que falhou
  5. Implantar o .war e verificar sem sair do terminal
  6. O que catalina.out guarda e o que o stderr guarda
  7. Heap dentro do teto do cgroup, sem morrer pelo OOM killer
  8. Reversão: volte ao estado anterior em um comando
  9. Quando esse caminho não é o certo

O que existe de verdade em cPanel para Java

Não existe "Setup Java App" ao lado do Setup Node.js App. O caminho documentado pelo cPanel para Java é o Tomcat via Containers, descrito na documentação oficial em docs.cpanel.net/ea4/containers/tomcat-via-containers. O administrador do servidor instala o pacote EA4 correspondente, e cada conta que usa Java ganha uma instância de Tomcat isolada, rodando em container, com o próprio conjunto de processos e o próprio limite de recursos.

Isso muda o modelo mental. Você não está subindo um Tomcat compartilhado onde várias contas depositam .war em um mesmo webapps. Você tem uma JVM por conta. Ela sobe, cai e é reiniciada no escopo da conta, escuta em uma porta própria e não aparece na internet diretamente.

Duas consequências práticas, e são as que determinam todo o resto do artigo:

A cadeia completa de uma requisição, do navegador ao servlet

Vale desenhar a cadeia antes de mexer em qualquer coisa, porque cada elo tem um sintoma de falha diferente.

navegador
  |  https://exemplo.com.br/loja/
  v
Apache / LiteSpeed  (TLS termina aqui, certificado do domínio)
  |  http://127.0.0.1:<porta>/loja/   (proxy reverso, texto claro, loopback)
  v
Tomcat em container (conector HTTP)
  |  context path /loja
  v
servlet / Spring Boot embutido no loja.war

O certificado é do domínio e vive no servidor web da frente. O Tomcat não enxerga TLS, não precisa de keystore, não precisa de conector 8443. Se a aplicação gera URL absoluta, ela vai montar http:// em vez de https:// a menos que o proxy envie os cabeçalhos X-Forwarded-Proto e X-Forwarded-For e o Tomcat os interprete. Quem faz essa interpretação tem nome: a RemoteIpValve, declarada no <Host> ou no <Engine> do server.xml, ou a RemoteIpFilter no web.xml da aplicação. Sem ela, os cabeçalhos chegam e são ignorados: request.isSecure() continua false e getScheme() continua http.

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       internalProxies="127\.0\.0\.1|::1"
       remoteIpHeader="x-forwarded-for"
       protocolHeader="x-forwarded-proto"
       protocolHeaderHttpsValue="https" />

O internalProxies é uma expressão regular com os IPs em que a valve confia. Deixe só o loopback, já que o proxy da frente fala com o container por 127.0.0.1. Abrir esse padrão demais permite que um cliente forje X-Forwarded-For e envenene o IP registrado no log e nas regras de bloqueio da aplicação. Esse é o motivo número um de redirecionamento infinito depois que tudo "já funcionava".

O 404 na raiz que prova que o Tomcat está vivo

Aqui está o detalhe que quase nenhum tutorial escreve, e que faz desenvolvedor experiente perder uma tarde.

Você implanta loja.war. O Tomcat descompacta e registra o contexto /loja. Você testa a raiz do container para ver se ele está vivo:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<porta>/

E recebe 404.

Isso não é erro. Com apenas loja.war implantado, não existe aplicação mapeada em ROOT, ou seja, no context path vazio. O Tomcat recebe a requisição, resolve o host, procura um contexto para /, não acha e responde 404 gerado por ele mesmo. Um 404 vindo do Tomcat significa, necessariamente, que o socket aceitou conexão, o protocolo HTTP foi falado e o container roteou. Backend vivo.

Se o Tomcat estivesse parado, curl nem chegaria a um código de status: você receberia Connection refused ou um timeout. A distinção entre "sem resposta" e "404" é o primeiro bit de informação do diagnóstico.

O critério de sucesso é um só, do começo ao fim: /loja/ responde 200. Nada mais. Não teste a raiz, não teste /manager, não conclua nada a partir do que o navegador mostra com cache.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:<porta>/loja/
curl -s -o /dev/null -w '%{http_code}\n' https://exemplo.com.br/loja/

Os dois precisam dar 200. Se o primeiro dá 200 e o segundo não, o problema é o proxy. Se o primeiro não dá 200, nem olhe o proxy ainda.

Do código de status ao elo que falhou

Cada combinação aponta para um elo específico da cadeia. Use a tabela antes de editar qualquer arquivo.

O que você vê Onde testou Significado Onde mexer
Connection refused loopback, porta do conector JVM não está no ar ou escuta em outra porta logs de inicialização do Tomcat
404 em / loopback Tomcat vivo, sem app em ROOT. Normal não mexa, siga para /loja/
404 em /loja/ loopback .war não implantado ou falhou ao subir catalina.out, permissões do arquivo
200 em /loja/ loopback backend correto agora sim, configure o proxy
502 Bad Gateway domínio público proxy ativo, backend ausente ou porta errada porta no proxy, estado da JVM
404 em /loja/ domínio público, 200 no loopback proxy aponta para outro caminho ou outro contexto regra de proxy, prefixo preservado
200 com CSS quebrado domínio público URL absoluta sem X-Forwarded-Proto cabeçalhos do proxy
Redirect infinito domínio público app força HTTPS, proxy diz http X-Forwarded-Proto e confiança no conector

A regra curta: 502 é proxy sem backend; 404 em /loja/ é war não implantado. São problemas diferentes e não se resolvem no mesmo arquivo.

Implantar o .war e verificar sem sair do terminal

A documentação oficial do cPanel descreve o fluxo de instalação do Tomcat em container e a área da conta onde o .war é depositado: o diretório ~/ea-tomcat<versão>/webapps no home do usuário (por exemplo ~/ea-tomcat10/webapps), e o controle do ciclo de vida da instância pelo ubic, com ubic start|stop|restart ea-tomcat<versão> executado como o próprio usuário da conta. O número da versão acompanha o pacote EA4 instalado, então confirme em docs.cpanel.net/ea4/containers/tomcat-via-containers qual está no seu servidor antes de digitar o caminho.

O que vale em qualquer versão:

O nome do arquivo é o context path

O nome do arquivo vira o context path. loja.war responde em /loja. Se você quer / como contexto, o arquivo precisa se chamar ROOT.war. Renomear loja.war para app.war depois do deploy não renomeia o contexto já expandido: o Tomcat passa a ter os dois.

Envie por SCP ou SFTP e confira o hash dos dois lados

Um .war de Spring Boot passa fácil dos 40 MB. Upload por navegador trunca com mais frequência do que se admite, e um .war truncado produz exatamente o sintoma do 404 em /loja/. Confira o hash dos dois lados.

sha256sum target/loja.war          # na sua máquina
ssh conta@servidor 'sha256sum ~/caminho/loja.war'

Reinicie a instância com o log aberto

O autodeploy pode estar ativo, mas não confie nele para a primeira publicação. Reinicie a instância e olhe o log enquanto a JVM sobe:

ubic restart ea-tomcat10        # troque 10 pela versão instalada
ubic status ea-tomcat10

Você quer ver a linha de deployment do contexto e o tempo total de startup.

Confirme pelo loopback antes de tocar no proxy

Só depois de ver 200 em http://127.0.0.1:<porta>/loja/ configure a regra de proxy reverso no domínio. Inverter essa ordem é o que produz uma hora depurando .htaccess enquanto o problema era uma dependência faltando no classpath.

O que catalina.out guarda e o que o stderr guarda

São duas superfícies distintas e elas não contam a mesma história.

Fonte Conteúdo típico Quando olhar
catalina.out startup, deployment de contexto, stack trace da aplicação, shutdown 404 em /loja/, 500, app subindo lenta
stderr do container falha antes da JVM inicializar, erro de flag de JVM, OOM Connection refused, processo que não fica de pé
log de erro do Apache/LiteSpeed do domínio falha do proxy, timeout, conexão recusada no upstream 502, 504

A sequência que resolve a maior parte dos casos: abra catalina.out, procure a linha de deployment do seu contexto e veja se ela existe. Se existir e logo abaixo houver uma stack trace, o .war chegou inteiro e a aplicação quebrou na inicialização, o que é um problema de código ou de configuração da aplicação, não de hospedagem. Se a linha de deployment não existe, o arquivo não foi visto: nome, permissão ou diretório errado.

tail -n 200 -f <caminho>/logs/catalina.out
grep -nE 'Deploying|Deployment of|SEVERE|Caused by' <caminho>/logs/catalina.out | tail -40

Uma stack trace longa se lê de baixo para cima: o último Caused by é a causa real.

Heap dentro do teto do cgroup, sem morrer pelo OOM killer

Este é o ponto onde hospedagem compartilhada castiga quem copia configuração de VM.

A JVM não consome apenas o heap. Consome heap mais metaspace, mais stacks de thread, mais buffers diretos, mais code cache, mais o próprio runtime. Se você fixar -Xmx colado no teto de memória da conta, o processo morre por OOM do cgroup sem nenhuma exceção Java no log: o kernel mata, e catalina.out simplesmente para no meio de uma linha. O sintoma na frente é 502.

Descubra o teto antes de escolher o número:

# cgroup v2
cat /sys/fs/cgroup/memory.max

# cgroup v1
cat /sys/fs/cgroup/memory/memory.limit_in_bytes

Um valor muito alto, na casa dos exabytes, significa que não há limite nesse arquivo e o teto está em outra camada. Pergunte ao provedor qual é o limite da conta em vez de adivinhar.

Com o número em mãos, reserve folga para o que não é heap. Em vez de fixar um valor absoluto, prefira a flag que a própria JVM usa para respeitar container:

-XX:MaxRAMPercentage=50.0

Essa flag depende de UseContainerSupport, que existe a partir do JDK 8u191 e do JDK 10 (ligada por padrão nesses builds). Em JVM mais antiga, o equivalente grosseiro era -XX:MaxRAMFraction=2, que é flag de produto e não exige UnlockExperimentalVMOptions; o unlock se aplicava a -XX:+UseCGroupMemoryLimitForHeap, experimental nos builds anteriores ao 8u191. Já MaxRAMPercentage não é reconhecida nesses builds: a JVM aborta o start com Unrecognized VM option 'MaxRAMPercentage=50.0' e o Tomcat nem sobe, o que no loopback aparece como Connection refused. E, sem a flag, o heap default sai da memória visível ao processo, que em JVM sem suporte a cgroup é a memória do host. Em uma máquina de 128 GB isso vira um -Xmx de dezenas de gigabytes dentro de uma conta de 1 GB, e o processo morre no primeiro pico. Confirme antes com java -XX:+PrintFlagsFinal -version | grep -E 'MaxRAMPercentage|UseContainerSupport|MaxHeapSize'.

Ela calcula o heap máximo como fração da memória visível ao container, e isso sobrevive a uma mudança de plano sem reedição. Se precisar de valor fixo, deixe margem e meça com a aplicação sob carga real antes de subir o número. -Xms igual a -Xmx é bom em servidor dedicado e ruim aqui: aloca tudo de cara e ocupa espaço que você poderia precisar para o resto da conta.

Uma trava adicional que evita vazamento de threads em aplicação com pool mal configurado: baixe o maxThreads do conector HTTP no server.xml, que vem em 200 por padrão. Cada thread reserva stack (1 MB por padrão em x86_64 de 64 bits, controlado por -Xss), e 200 threads ativas são 200 MB fora do heap. Em conta com 1 a 2 GB de teto, algo entre 25 e 50 é mais honesto com a memória disponível: <Connector port="..." protocol="HTTP/1.1" maxThreads="50" acceptCount="50" />. Com todas as threads ocupadas, novas conexões ficam na fila do acceptCount; estourada a fila, o cliente vê conexão recusada no nível TCP ou timeout, não 503. O Tomcat não emite 503 por saturação de pool: esse código vem de rejeição explícita da aplicação ou do proxy. Vale anotar a ambiguidade: Connection refused no loopback pode ser JVM fora do ar ou fila cheia, e quem separa os dois é o catalina.out (se há linhas de requisição sendo servidas, a JVM está viva e o problema é saturação). De todo modo, é um modo de falha bem mais fácil de diagnosticar que OOM silencioso.

Reversão: volte ao estado anterior em um comando

Tenha o plano de volta pronto antes do deploy, não depois do 502.

O que guardar antes de publicar

Guarde o artefato que está no ar e a configuração atual.

cp loja.war ~/backup/loja-$(date +%Y%m%d-%H%M).war
cp ~/ea-tomcat<versão>/conf/server.xml ~/backup/server.xml.bak

Como desfazer o deploy sem servir a versão velha

  1. Remova o .war novo e o diretório expandido com o mesmo nome. Deixar o diretório antigo faz o Tomcat servir a versão velha descompactada e você jura que o rollback não funcionou.
  2. Restaure o .war anterior do backup.
  3. Reinicie a instância.
  4. Confirme com o mesmo critério de sempre: curl em /loja/ pelo loopback, depois pelo domínio. 200 nos dois.

Desligar o Java sem deixar 502 na cara do visitante

Se a decisão for abortar a migração, remova primeiro a regra de proxy reverso do domínio e só depois pare o container. Na ordem inversa, o intervalo entre as duas ações é tempo de 502 na cara do visitante.

Quando esse caminho não é o certo

Contra o interesse de qualquer provedor, incluindo o nosso: nem toda aplicação Java deve morar em container dentro de conta cPanel.

Se o seu .war sobe em 90 segundos, carrega um contexto Spring com dezenas de beans e precisa de 2 GB de heap estável, você está pedindo a uma conta de hospedagem compartilhada um perfil de consumo que ela não foi desenhada para sustentar. Vai funcionar nos primeiros dias e vai começar a cair quando o restante da conta crescer. VPS ou servidor dedicado resolve melhor e sai mais barato que o tempo gasto perseguindo OOM.

O caminho do Tomcat em container entrega muito bem outro perfil: aplicação interna, painel administrativo, API de baixo volume, serviço legado que precisa continuar de pé enquanto o resto migra. Para esses casos, ele é o caminho documentado pelo cPanel para esse perfil, está descrito na documentação oficial e funciona.

E o critério continua sendo um só, sempre o mesmo: /loja/ devolvendo 200.

Referências

  1. Documentação oficial (cpanel) — Tomcat via Containers. Consultado em 2026-10-07.
Leia também