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.

Resposta curta: 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.
Neste artigo
- O que o Setup Ruby App faz por baixo do painel
- O que salvar antes de criar a aplicação para poder voltar atrás
- Como preencher Application Root, Application URL e startup file
- Por que rodar o bundle pelo botão do painel e não pelo SSH
- RAILS_ENV, SECRET_KEY_BASE e as variáveis sem as quais o boot aborta
- A URL devolve 500 e o painel mostra a aplicação ativa
- Checklist de publicação e quando o limite é a hospedagem compartilhada
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 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
.htaccessna 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
.zipfora 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 obundle installreescreve. Duplique comoGemfile.lock.bakantes 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 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
GemfileeGemfile.lockversionados. - Criar a aplicação apontando para um subdomínio de teste.
- Definir
RAILS_ENV=productioneSECRET_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.logantes 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, 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.
Referências
- Documentação oficial (cpanel) — How to Create Ruby Web Applications. Consultado em 2026-09-29.