blog
Painéis

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.

JR · · 6 min de leitura · 3 tabelas · 2 blocos de código

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
  1. O que o Setup Ruby App faz por baixo do painel
  2. O que salvar antes de criar a aplicação para poder voltar atrás
  3. Como preencher Application Root, Application URL e startup file
  4. Por que rodar o bundle pelo botão do painel e não pelo SSH
  5. RAILS_ENV, SECRET_KEY_BASE e as variáveis sem as quais o boot aborta
  6. A URL devolve 500 e o painel mostra a aplicação ativa
  7. 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 que salvar antes de criar a aplicação para poder voltar atrás

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

  1. 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.
  2. 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 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:

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.

Sequência de publicação de um app Rails no cPanelCriar aplicaçãoRoot, URL e config.ruVariáveisRAILS_ENV e SECRET_KEY_BASEBundle installPelo botão do painelAssets e migraçõesPrecompile e db:migrateRestartAbrir a URL do app
Ordem que evita a maioria dos 500 na primeira subida. Nomes de pasta e domínio da tela são exemplos.

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.

Do 500 à causa: leitura do stderr.logURL devolve 500Painel mostra app ativoLer stderr.logÚltimas 50 linhas, de baixo para cimaGem faltando ou versãoRun Bundle Install e RestartSecret ou migraçãoVariável, db:migrate, RestartTela sem CSSassets:precompileGem nativa não compilaLimite do compartilhado, use VPS
Caminho de diagnóstico a partir do que o stderr.log mostra. Só o último caso exige mudar de ambiente.

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

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

  1. Subir o código com Gemfile e Gemfile.lock versionados.
  2. Criar a aplicação apontando para um subdomínio de teste.
  3. Definir RAILS_ENV=production e SECRET_KEY_BASE.
  4. Rodar o bundle pelo botão do painel.
  5. 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.
  6. Precompilar assets.
  7. Clicar em Restart e abrir a URL.
  8. 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, 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

  1. Documentação oficial (cpanel) — How to Create Ruby Web Applications. Consultado em 2026-09-29.
Leia também