blog
Painéis

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.

JR · · 8 min de leitura · 1 tabela · 9 blocos de código

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
  1. Os quatro campos do Application Manager e o que cada um exige
  2. Por que o restart depende de um arquivo vazio chamado restart.txt
  3. stderr.log, o arquivo que explica quase todo boot quebrado
  4. Três falhas de boot lidas linha a linha no stderr.log
  5. Variáveis de ambiente pela interface e por que PORT não é sua
  6. 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:

  1. Cada alteração de variável exige restart. Edite, salve, touch tmp/restart.txt, bata na URL.
  2. 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.example versionado com os nomes das variáveis, nunca com os valores.
  3. PORT não é sua. Não declare PORT manualmente 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:

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

  1. Documentação oficial (cpanel) — Application Manager (cPanel). Consultado em 2026-09-15.
Leia também