# 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.

> 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.

João Rizzon · 2026-10-13 · Infraestrutura web

---

## 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](https://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á `OutOfMemoryError` elegante, 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`.

```xml
<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](https://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 `.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.
- Restaure o `.war` anterior do backup.
- Reinicie a instância.
- 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.

