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.

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
- O que existe de verdade em cPanel para Java
- A cadeia completa de uma requisição, do navegador ao servlet
- O 404 na raiz que prova que o Tomcat está vivo
- Do código de status ao elo que falhou
- Implantar o .war e verificar sem sair do terminal
- O que catalina.out guarda e o que o stderr guarda
- Heap dentro do teto do cgroup, sem morrer pelo OOM killer
- Reversão: volte ao estado anterior em um comando
- 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 JVM consome do teto de memória da conta. Heap mal configurado não dá
OutOfMemoryErrorelegante, dá processo morto pelo OOM killer do cgroup. - O que o navegador fala não é o Tomcat. É o Apache ou o LiteSpeed da frente, que termina TLS e repassa para o conector HTTP do container.
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
- Remova o
.warnovo 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. - Restaure o
.waranterior do backup. - Reinicie a instância.
- Confirme com o mesmo critério de sempre:
curlem/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
- Documentação oficial (cpanel) — Tomcat via Containers. Consultado em 2026-10-07.