# Rails no cPanel: do Setup Ruby App ao 500 no stderr.log

Do formulário do Setup Ruby App até a leitura do stderr.log do Passenger, com o que salvar antes de cada passo para conseguir voltar atrás.

> crie a aplicação em Software > Setup Ruby App apontando o Application Root para a pasta do projeto, rode o bundle pelo botão do painel, defina RAILS_ENV=production e SECRET_KEY_BASE, precompile os assets e clique em Restart. Se a URL devolver 500, a causa está nas últimas linhas do stderr.log.

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

---

## O que o Setup Ruby App faz por baixo do painel

No cPanel, o item **Setup Ruby App** (menu Software) cria uma aplicação servida pelo **Phusion Passenger**. Você não sobe um `rails server` nem escolhe porta: o Passenger inicia o processo quando chega a primeira requisição e o mantém vivo enquanto houver tráfego. A [documentação do cPanel](https://docs.cpanel.net/knowledge-base/web-services/how-to-create-ruby-web-applications/) descreve esse fluxo e os campos do formulário.

Três consequências práticas disso:

- O painel cria um **virtualenv de Ruby** próprio para a aplicação, isolado do Ruby do sistema. As gems instaladas valem só para aquele app.
- A configuração do Apache é gerada pelo painel. Editar `.htaccess` na pasta da aplicação para "corrigir" o Passenger normalmente quebra, não arruma.
- Quando o app falha ao iniciar, o navegador recebe **500 Internal Server Error** e a tela do painel não mostra o motivo. O motivo está no `stderr.log`.

## O que salvar antes de criar a aplicação para poder voltar atrás

Todo passo abaixo é reversível se você guardar duas coisas.

- **Backup da pasta da aplicação.** No **Gerenciador de Arquivos**, clique com o botão direito na pasta do app, escolha **Compress**, formato Zip, e guarde o `.zip` fora da pasta (em `/home/usuario/backups`, por exemplo). Para restaurar: apague a pasta e use **Extract** no zip.
- **Cópia do `Gemfile.lock`.** É o arquivo que o `bundle install` reescreve. Duplique como `Gemfile.lock.bak` antes de qualquer instalação de gem. Se o bundle resolver uma versão incompatível, você volta o arquivo e reinstala.

E guarde na cabeça o botão **Restart** da tela do app: ele não é um "tentar de novo", é o que faz o Passenger reler variáveis de ambiente, código e gems. Alterou qualquer coisa, clique em Restart antes de concluir que não funcionou.

## Como preencher Application Root, Application URL e startup file

Em **Software > Setup Ruby App**, clique em **Create Application** e preencha:

| Campo | O que colocar | Observação |
|---|---|---||
| Ruby version | A versão que o seu `Gemfile` exige | Mudar depois obriga a refazer o `bundle install` |
| Application root | Caminho relativo a `/home/usuario`, ex.: `apps/minhaloja` | Pasta onde ficam `Gemfile`, `config/`, `app/` |
| Application URL | Domínio ou subdomínio e, opcionalmente, um subcaminho | Define onde o app responde |
| Application startup file | `config.ru` no Rails | Arquivo que o Passenger carrega |
| Environment variables | `RAILS_ENV`, `SECRET_KEY_BASE`, variáveis de banco | Detalhado adiante |

Os nomes de pasta e domínio acima são **exemplos**, troque pelos seus.

### Por que o domínio passa a responder a partir de public/

Aplicação Rails não serve a raiz do projeto. O que vai para a web é `public/`, e só. A [documentação do cPanel](https://docs.cpanel.net/knowledge-base/web-services/how-to-create-ruby-web-applications/) indica que a aplicação é servida a partir da pasta `public` dentro do Application Root. Na prática, depois de criar o app, o domínio passa a responder a partir de `public/`, e o conteúdo antigo que estava em `public_html` deixa de aparecer na URL: o domínio não aponta mais para lá.

Dois cuidados:

- **Não crie o app apontando para um domínio que já tem site em produção** sem backup. Use um subdomínio de teste primeiro, ex.: `app.seudominio.com.br`.
- Para desfazer, remova a aplicação em **Setup Ruby App** e reaponte o Document Root do domínio em **Domains**.

## Por que rodar o bundle pelo botão do painel e não pelo SSH

Na tela da aplicação existe o campo **Configuration files** (ou equivalente, conforme a versão do cPanel). Informe `Gemfile` e salve: aparece o botão **Run Bundle Install** (ou **Bundle install**). Clique nele.

Use esse botão em vez de abrir o Terminal pela razão simples de que ele executa o bundler **dentro do ambiente Ruby da aplicação**, com as variáveis certas já carregadas. Rodar `bundle install` numa sessão SSH crua costuma instalar gems para outro Ruby, e o app continua acusando gem faltando mesmo com a gem instalada.

Se você precisar mesmo do terminal, a tela do app mostra no topo a linha de ativação do ambiente, algo como `source /home/usuario/rubyvenv/apps/minhaloja/3.2/bin/activate`. Copie exatamente a linha que o **seu** painel exibe (o caminho muda conforme usuário, pasta e versão), cole no Terminal, e só depois rode `bundle install`.

Deu erro na instalação de uma gem nativa? Volte o `Gemfile.lock.bak`, ajuste a versão da gem no `Gemfile` e rode de novo. Em hospedagem compartilhada você não instala pacotes de sistema; gems que exigem bibliotecas ausentes precisam de alternativa em Ruby puro.

## RAILS_ENV, SECRET_KEY_BASE e as variáveis sem as quais o boot aborta

Na mesma tela, em **Environment variables**, clique em **Add Variable** para cada uma:

| Nome | Valor | Para que serve |
|---|---|---||
| `RAILS_ENV` | `production` | Sem isso o Rails sobe em development e procura gems do grupo de teste |
| `SECRET_KEY_BASE` | string longa gerada por você | Assina cookies e sessões; ausente, o Rails aborta o boot |
| `RAILS_SERVE_STATIC_FILES` | `1` | Útil quando o app precisa servir os próprios assets |

Para gerar o `SECRET_KEY_BASE`, rode `bundle exec rails secret` com o ambiente ativado e cole a saída no campo de valor. Trate essa string como senha: ela não vai para o Git nem para o chat do cliente.

Depois de salvar as variáveis, clique em **Restart**. Variável adicionada sem restart não chega ao processo já em execução.

### Precompilar os assets quando a tela abre sem CSS nem JavaScript

Com o ambiente ativado no Terminal, dentro da pasta do app:

```
cd ~/apps/minhaloja
RAILS_ENV=production bundle exec rails assets:precompile
```

Esperado: linhas de compilação e o aparecimento de `public/assets/` com arquivos de nome longo. Se a tela abrir sem CSS nem JavaScript, esse é o passo que faltou. Para desfazer, `bundle exec rails assets:clobber` apaga o que foi gerado.

Migrações seguem a mesma lógica: `RAILS_ENV=production bundle exec rails db:migrate`, com backup do banco feito antes em **Bancos de Dados > phpMyAdmin > Exportar**.

## A URL devolve 500 e o painel mostra a aplicação ativa

O painel mostra a aplicação como ativa e o navegador devolve 500. A causa está no log de erro do Passenger, que não aparece na tela.

### Onde o stderr.log fica e por que ler de baixo para cima

No **Gerenciador de Arquivos**, entre na pasta da aplicação e procure `stderr.log`. Dependendo da configuração, ele está na raiz do Application Root ou em `log/`. Clique com o botão direito e escolha **View** (ou **Edit**) para ler sem baixar. Rails também grava `log/production.log`: vale olhar os dois.

Pela linha de comando, as últimas linhas bastam:

```
tail -n 50 ~/apps/minhaloja/stderr.log
```

Leia **de baixo para cima**. O erro que derrubou o boot é o último bloco, e a primeira linha útil costuma vir logo acima do rastreamento de pilha.

### Seis mensagens típicas do stderr.log e o que cada uma pede

| O que aparece no stderr.log | Causa provável | O que fazer |
|---|---|---||
| `Could not find <gem> in locally installed gems` | `bundle install` não rodou nesse ambiente, ou rodou em outro Ruby | Botão **Run Bundle Install** na tela do app, depois **Restart** |
| `Your Ruby version is X, but your Gemfile specified Y` | Versão escolhida no painel diferente da do projeto | Alinhe o campo Ruby version ou o `Gemfile`, e refaça o bundle |
| `Missing secret_key_base` | Variável de ambiente ausente ou não aplicada | Adicione `SECRET_KEY_BASE` e clique em **Restart** |
| `PG::ConnectionBad` / `Mysql2::Error: Access denied` | Credenciais ou host do banco errados | Confira usuário, senha e `host: localhost` nas variáveis. A linha do `PG::` só se aplica se o ambiente oferecer PostgreSQL; em hospedagem compartilhada o padrão é MySQL |
| `Migrations are pending` | Banco criado mas não migrado | `rails db:migrate` com `RAILS_ENV=production` |
| `The asset "application.css" is not present in the asset pipeline` | Assets não precompilados | `rails assets:precompile` |

Depois de qualquer correção: **Restart**, recarregue a URL, e leia o `stderr.log` de novo. Ele acumula; o bloco novo fica no fim.

## Checklist de publicação e quando o limite é a hospedagem compartilhada

Sequência que evita a maioria dos 500 na primeira subida:

- Subir o código com `Gemfile` e `Gemfile.lock` versionados.
- Criar a aplicação apontando para um **subdomínio de teste**.
- Definir `RAILS_ENV=production` e `SECRET_KEY_BASE`.
- Rodar o bundle pelo botão do painel.
- Criar banco e usuário em **Bancos de Dados MySQL** (ou em **Bancos de Dados PostgreSQL**, se o seu painel exibir esse item e o app usar Postgres), rodar as migrações.
- Precompilar assets.
- Clicar em **Restart** e abrir a URL.
- Se vier 500, ler as últimas 50 linhas do `stderr.log` antes de mexer em qualquer coisa.

E o conselho que não vende upgrade: se o `stderr.log` acusa gem nativa que não compila, extensão de sistema ausente ou necessidade de processos de background permanentes (Sidekiq, Action Cable com WebSocket persistente), o limite não é o plano, é o modelo de hospedagem compartilhada. Nesse caso, um VPS resolve e um plano maior no mesmo ambiente não. Já se o log acusa migração pendente, secret ausente ou asset não compilado, é configuração: resolve em minutos, sem trocar nada.

Este guia se apoia na documentação oficial do cPanel sobre [criação de aplicações Ruby](https://docs.cpanel.net/knowledge-base/web-services/how-to-create-ruby-web-applications/), consultada em 29/09/2026. Caminhos de pasta, nomes de domínio e versões citados são exemplos; os valores reais aparecem na tela do seu painel.

