Node.js no cPanel compartilhado: lendo o stderr.log do Passenger
Onde o Passenger escreve o erro de boot, por que o restart passa por um arquivo vazio e quando a conta compartilhada deixa de ser o lugar certo.

Resposta curta: são quatro campos obrigatórios no Application Manager (deployment domain, application root relativo à home, application URL e startup file), restart por `touch tmp/restart.txt`, e todo erro de boot cai em `~/<application root>/stderr.log`.
Neste artigo
- Os quatro campos do Application Manager e o que cada um exige
- Por que o restart depende de um arquivo vazio chamado restart.txt
- stderr.log, o arquivo que explica quase todo boot quebrado
- Três falhas de boot lidas linha a linha no stderr.log
- Variáveis de ambiente pela interface e por que PORT não é sua
- Quando o Application Manager não dá conta e vale parar de insistir
O Application Manager do cPanel é uma tela curta: quatro campos obrigatórios, um seletor de modo e uma lista de variáveis de ambiente. O que ela não mostra é onde o Passenger escreve quando a aplicação morre no boot. É esse arquivo que decide se você resolve em dois minutos ou passa a tarde recarregando a URL e vendo o mesmo erro genérico do navegador.
Tudo aqui vem da documentação oficial do Application Manager (cPanel 102). Não há medição própria nesta página: nenhum benchmark, nenhum tempo de boot cronometrado. Os caminhos, as mensagens de log e os trechos de código são exemplos construídos a partir do comportamento documentado, e estão identificados como exemplos.
Os quatro campos do Application Manager e o que cada um exige
A interface fica em cPanel > Software > Application Manager > Register Application. Os campos:
| Campo | O que a interface espera | Erro típico de quem preenche rápido |
|---|---|---|
| Deployment Domain | Domínio ou subdomínio já existente na conta | Digitar um subdomínio que ainda não foi criado em Domains |
| Application Root | Caminho relativo à home, sem /home/usuario na frente |
Colar o caminho absoluto do pwd |
| Application URL | Caminho que vem depois do domínio (vazio = raiz) | Pôr barra inicial e duplicar o segmento |
| Application Startup File | Arquivo de entrada relativo à Application Root | Apontar index.js quando o arquivo é src/index.js |
O ponto que mais custa tempo é o Application Root ser relativo à home. Se a aplicação está em /home/usuario/apps/api, o campo recebe apps/api. Nada mais. O cPanel resolve o resto.
O Application URL é o inverso: ele é relativo ao domínio escolhido. Com domínio exemplo.com e URL api, a aplicação responde em https://exemplo.com/api. Deixar vazio publica na raiz do domínio, o que sobrescreve o que quer que o public_html daquele domínio estivesse servindo.
E o Application Mode, com as opções Production e Development. A documentação do Application Manager não detalha a diferença de comportamento entre os dois, e o que existe aqui é comportamento conhecido do Passenger, fora da fonte citada: o modo define o ambiente em que a aplicação é executada. Regra prática: sobe em Development enquanto você está depurando o boot, troca para Production quando parar de quebrar.
Por que o restart depende de um arquivo vazio chamado restart.txt
Você não tem systemctl numa conta compartilhada. O Passenger resolve isso por mtime: ele observa o arquivo tmp/restart.txt dentro da Application Root e, quando o timestamp muda, derruba os processos da aplicação e sobe de novo na próxima requisição.
cd ~/apps/api
mkdir -p tmp
touch tmp/restart.txt
O arquivo pode ficar vazio para sempre. O conteúdo é irrelevante, o que importa é o mtime. A interface do Application Manager tem um botão de restart que faz exatamente isso, e o touch via SSH ou via terminal do cPanel é o mesmo efeito sem abrir o navegador.
Detalhe que esquece: o restart é preguiçoso. Nada acontece no instante do touch. O processo novo só sobe quando chega a primeira requisição depois dele. Se você faz touch e vai direto olhar o log, pode não ter log nenhum ainda. Faça o touch, bata na URL, depois leia.
stderr.log, o arquivo que explica quase todo boot quebrado
Quando a aplicação não sobe, o navegador mostra uma página de erro do servidor web. Ela não serve para nada. O que serve é:
~/<application root>/stderr.log
Para uma Application Root apps/api, o caminho completo é /home/usuario/apps/api/stderr.log. O Passenger escreve ali a saída de erro padrão do processo da aplicação, que é onde cai o stack trace do Node e o traceback do Python.
O fluxo de diagnóstico que funciona:
touch ~/apps/api/tmp/restart.txt
curl -sS -o /dev/null -w '%{http_code}\n' https://exemplo.com/api
tail -n 40 ~/apps/api/stderr.log
E para acompanhar enquanto recarrega no navegador:
tail -f ~/apps/api/stderr.log
Se o arquivo não existe, a aplicação provavelmente nunca chegou a ser iniciada, e aí o problema está no registro (domínio, root ou startup file) e não no código.
Três falhas de boot lidas linha a linha no stderr.log
Os blocos abaixo são exemplos construídos, não captura de um incidente real. O formato segue o que Node e Python emitem em stderr e o que o Passenger encaminha para o stderr.log.
Cannot find module quando a dependência foi instalada no interpretador errado
Error: Cannot find module 'express'
Require stack:
- /home/usuario/apps/api/app.js
at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1077:15)
Leitura: o startup file foi encontrado e executado, logo os campos de registro estão certos. O que faltou foi dependência. Em conta compartilhada o npm install precisa rodar no mesmo ambiente que o Passenger usa para subir a aplicação, não no shell cru. O algoritmo de resolução do Node sobe os diretórios pais procurando node_modules, então até um ~/node_modules seria encontrado: a causa do erro não é essa. O que quebra é o interpretador ser outro. A aplicação registrada roda sob a versão de Node (ou sob o virtualenv Python) que o Application Manager provisionou, e pacote instalado por um node ou python diferente do shell vai parar em outro prefixo e, quando o módulo é nativo, compilado contra uma ABI que o interpretador da aplicação não aceita. O botão Run NPM Install na linha da aplicação roda a instalação nesse ambiente. Para Python a documentação citada não descreve botão equivalente: instale as dependências com o pip do virtualenv que a aplicação usa, nunca com o pip do shell, apontando para o requirements.txt na Application Root.
app.listen(3000) sob Passenger e quem é dono da porta
Sob Passenger, app.listen(3000) normalmente não gera erro nenhum: o módulo de suporte do Passenger intercepta http.Server.listen e substitui o endereço pelo socket que ele mesmo já abriu, ignorando a porta pedida. O erro abaixo é o que aparece quando esse mesmo código roda fora do Passenger (dois processos disputando a 3000 no seu terminal) ou quando a aplicação abre um socket por conta própria, sem passar pelo http.Server:
Error: listen EADDRINUSE: address already in use :::3000
at Server.setupListenHandle [as _listen2] (node:net:1817:16)
Leitura: quem é dono do socket sob Passenger é o Passenger, e ele entrega o endereço pelo ambiente. A aplicação não escolhe porta, e código que assume a porta escolhida (log, health check batendo em 3000, um segundo listener) falha de formas menos óbvias que um erro de boot.
// errado em Passenger
app.listen(3000);
// certo
app.listen(process.env.PORT);
Se você precisa que o mesmo código rode local e sob Passenger, app.listen(process.env.PORT || 3000) resolve os dois casos sem if. Em Python, o equivalente é não chamar app.run() no corpo do módulo: o Passenger importa o objeto WSGI e ele mesmo serve. app.run() solto no import é causa clássica de boot que trava.
Startup file apontando para um arquivo que não existe
Error: Cannot find module '/home/usuario/apps/api/index.js'
at Module._load (node:internal/modules/cjs/loader:922:27)
Leitura: repare que o caminho do erro é absoluto e contém a Application Root concatenada com o startup file. O arquivo real é src/index.js ou server.js, e o campo ficou com o default. Corrija o campo Application Startup File para o caminho relativo à root, salve, e dê o touch no tmp/restart.txt. Não mova o arquivo para a raiz só para casar com o formulário: o campo aceita subdiretório.
Variáveis de ambiente pela interface e por que PORT não é sua
Na linha da aplicação registrada, a interface permite adicionar pares de nome e valor que entram no ambiente do processo. É assim que você passa NODE_ENV, string de conexão de banco, chave de API.
Três regras que evitam retrabalho:
- Cada alteração de variável exige restart. Edite, salve,
touch tmp/restart.txt, bata na URL. - O valor fica salvo na configuração da conta, não no repositório. Isso é bom para segredo, e é exatamente por isso que ele some quando você recria a aplicação do zero. Mantenha um
.env.exampleversionado com os nomes das variáveis, nunca com os valores. PORTnão é sua. Não declarePORTmanualmente ali, porque é o Passenger que a define.
Para conferir o que chegou de fato ao processo, um endpoint temporário listando só as chaves (nunca os valores) resolve:
app.get('/_env', (req, res) => res.json(Object.keys(process.env).sort()));
Remova depois. Endpoint de diagnóstico esquecido em produção é superfície de ataque.
Quando o Application Manager não dá conta e vale parar de insistir
O Application Manager cobre aplicação que vive dentro do ciclo de requisição HTTP. Fora disso, ele não é o lugar, e descobrir isso antes de migrar economiza um fim de semana. Os sinais:
- A aplicação precisa escutar numa porta própria. Se o requisito é um listener em porta fixa e acessível de fora, não dá: o Passenger é dono do socket.
- Há worker persistente fora do request. Fila, cron interno de segundo em segundo, consumidor de broker. O Passenger pode encerrar processos ociosos, e aí seu worker simplesmente para sem log de erro.
- WebSocket com conexão longa. Conexão que precisa ficar aberta por horas sob um proxy compartilhado é frágil por natureza.
- Dependência nativa que compila.
node-gyp, extensão C de Python. A compilação acontece sob o limite de memória do cgroup da conta, e o sintoma é o build morrer sem mensagem clara, com o processo levando um kill no meio.
O teste é barato: tente o npm install ou pip install pelo próprio Application Manager e leia o stderr.log. Se morreu na compilação, você já tem a resposta sem ter contratado nada. Se subiu, respondeu na URL e o stderr.log ficou quieto, você não precisa de VPS, e eu prefiro dizer isso a vender migração que não resolve problema nenhum.
Referências
- Documentação oficial (cpanel) — Application Manager (cPanel). Consultado em 2026-09-15.