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

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

João Rizzon · 2026-10-03 · Painéis

---

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)](https://docs.cpanel.net/cpanel/software/application-manager/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.

```bash
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:

```bash
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:

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

```js
// 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.example` versionado com os **nomes** das variáveis, nunca com os valores.
- `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:

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

