Site Jekyll em hospedagem cPanel: o passo a passo do build
O Setup Ruby App só roda o build; quem entrega as páginas é o Apache lendo a pasta _site. Entenda a diferença e o que fazer a cada alteração de conteúdo.

Resposta curta: dá para publicar um site Jekyll em hospedagem com cPanel em 4 etapas: criar a aplicação no Setup Ruby App, instalar as gems pelo botão Run Bundle Install, rodar `bundle exec jekyll build` no Terminal e apontar a raiz do domínio para a pasta `_site`.
Neste artigo
- O cPanel serve os arquivos, mas o build é você quem dispara
- O que conferir na conta antes de mexer na raiz do domínio
- Criar a aplicação Ruby que vai hospedar o Jekyll
- Instalar as gems pelo Run Bundle Install e o que fazer quando o botão não aparece
- Rodar o bundle exec jekyll build pelo Terminal da hospedagem
- Fazer o domínio apontar para a pasta _site
- O que acontece quando você edita um post e esquece de rodar o build
- Quando gerar o site na sua máquina e subir só o _site é a melhor escolha
O cPanel serve os arquivos, mas o build é você quem dispara
Jekyll gera HTML. Depois que o build termina, o site é um monte de arquivos estáticos numa pasta chamada _site. Servir esses arquivos é trabalho que qualquer hospedagem compartilhada já faz: o Apache lê a pasta e entrega os arquivos.
O que não é trivial é rodar o build dentro da hospedagem. Jekyll é uma aplicação Ruby, precisa de uma versão de Ruby, das gems certas e de um shell onde o jekyll build possa ser executado. É exatamente isso que o recurso Setup Ruby App do cPanel entrega, e a documentação oficial do cPanel descreve o procedimento passo a passo.
Dois pontos que evitam muita frustração depois:
- O Passenger não serve o seu site Jekyll. Ele é o servidor de aplicação que o Setup Ruby App configura, e nesse caso serve só como ambiente: é por causa dele que você ganha um Ruby isolado, um Gemfile e um comando para ativar o ambiente virtual. Quem entrega as páginas ao visitante é o Apache, lendo os arquivos estáticos.
- Cada alteração de conteúdo exige um novo build. Editou um post em Markdown? Enquanto você não rodar
jekyll buildoutra vez, o_sitecontinua com o HTML antigo, e é o HTML antigo que o visitante vê.
Se você já gera o site no seu computador, existe um caminho ainda mais curto: pular tudo isso e subir só a pasta _site por FTP ou pelo Gerenciador de Arquivos. Funciona, é menos coisa para dar errado, e eu digo isso sabendo que é o caminho que menos usa recurso do servidor. A seção final cobre essa alternativa.
O que conferir na conta antes de mexer na raiz do domínio
| Requisito | Onde conferir no cPanel | Se não existir |
|---|---|---|
| Recurso Setup Ruby App | Busque por "Ruby" ou "Setup Ruby App" na barra de busca do cPanel | Peça ao suporte; em alguns planos o recurso não está habilitado |
| Acesso ao Terminal ou SSH | Seção "Avançado" > "Terminal" | Sem Terminal ou SSH não dá para rodar o build no servidor: o botão Run Bundle Install só instala as gems. Nesse caso, gere o site na sua máquina e suba a pasta _site, como mostra a seção final |
| Domínio ou subdomínio criado | "Domínios" | Crie antes, porque você vai precisar mudar a raiz dele |
Arquivos do projeto Jekyll (com Gemfile) |
Gerenciador de Arquivos | Suba o projeto por FTP ou clone do Git |
Um aviso de risco antes de qualquer coisa: você vai mexer na raiz de documentos de um domínio. Se esse domínio já tem um site no ar, a mudança derruba o site atual na hora. Faça backup completo em "Backup" ou "Assistente de Backup" antes, e, se for só para testar, use um subdomínio novo (teste.seudominio.com.br, por exemplo) em vez do domínio principal.
Criar a aplicação Ruby que vai hospedar o Jekyll
Onde fica o Setup Ruby App no cPanel
No cPanel, digite "Ruby" na busca do topo e clique em Setup Ruby App. A tela lista as aplicações existentes e tem um botão para criar uma nova.
Os quatro campos da aplicação e o que colocar em cada um
São quatro campos principais:
- Ruby version: escolha uma das versões oferecidas pela lista. Jekyll é sensível à versão de Ruby, então anote qual você escolheu.
- Application root: a pasta do projeto, relativa à sua pasta home. Exemplo (fictício, use o nome que quiser):
jekyll_app. - Application URL: o domínio ou subdomínio associado. Aqui o cPanel só quer saber qual domínio a aplicação Passenger responde. Lembre que o site final não será servido por essa aplicação.
- Application startup file: pode ficar com o padrão. Jekyll não tem um
app.rbque o Passenger precise carregar.
Clique em Create. O cPanel cria a pasta, instala um ambiente Ruby isolado e mostra, no topo da tela da aplicação, um comando de ativação do ambiente virtual. Copie esse comando: você vai usá-lo no terminal.
Onde os arquivos do projeto precisam ficar para o cPanel enxergar o Gemfile
Abra o Gerenciador de Arquivos, entre na pasta que você definiu (jekyll_app, no exemplo) e envie os arquivos do seu projeto Jekyll: _config.yml, Gemfile, as pastas _posts, _layouts, _includes e o que mais existir. Se o projeto está no Git, dá para clonar pelo Terminal.
O Gemfile é obrigatório. É por ele que o cPanel sabe quais gems instalar. Um Gemfile mínimo para Jekyll tem esta cara (exemplo):
source "https://rubygems.org"
gem "jekyll"
Se o seu projeto usa tema e plugins, mantenha o Gemfile que já funciona na sua máquina. Trocar de Gemfile no meio do caminho é a forma mais rápida de transformar um erro simples num erro difícil de ler.
Instalar as gems pelo Run Bundle Install e o que fazer quando o botão não aparece
Volte para Setup Ruby App, abra a aplicação que você criou e procure o botão Run Bundle Install. Ele aparece quando o cPanel encontra um Gemfile na Application root. Clicar nele faz o cPanel executar o bundle install dentro do ambiente Ruby daquela aplicação, instalando tudo que o Gemfile pede.
Esse passo demora. Jekyll puxa várias dependências e algumas compilam código nativo. Deixe a aba aberta até terminar.
Se o botão não aparece:
- Confirme que o
Gemfileestá na raiz da aplicação, não dentro de uma subpasta. É o erro mais comum quando a pessoa sobe um.zipe ele descompacta criando uma pasta a mais. - Clique em Restart na aplicação e recarregue a página.
Se o bundle install falha, a mensagem costuma apontar uma gem específica. Duas causas frequentes: a versão de Ruby escolhida não é compatível com a versão da gem fixada no Gemfile.lock, ou falta um pacote de sistema para compilar a gem nativa. No primeiro caso, apague o Gemfile.lock e rode de novo. No segundo, não há o que fazer do seu lado: é um caso para abrir chamado com o suporte informando o nome da gem e a mensagem exata.
Rodar o bundle exec jekyll build pelo Terminal da hospedagem
Abra Terminal (seção Avançado do cPanel) ou conecte por SSH. Cole o comando de ativação do ambiente virtual que o Setup Ruby App mostrou na tela da aplicação. Ele tem mais ou menos este formato, e os caminhos variam conforme o seu usuário e a versão de Ruby:
source /home/SEU_USUARIO/virtualenv/jekyll_app/VERSAO/bin/activate && cd /home/SEU_USUARIO/jekyll_app
O sinal de que funcionou é o prompt passar a exibir o nome do ambiente entre parênteses. A partir daí, ruby e bundle apontam para o ambiente da aplicação, não para o Ruby do sistema.
Agora o build:
bundle exec jekyll build
Saída esperada: linhas informando a pasta de origem, a pasta de destino (.../jekyll_app/_site) e o tempo gasto na geração. Se terminar com "done", a pasta _site existe e está preenchida. Confira pelo Gerenciador de Arquivos: deve haver um index.html lá dentro.
O bundle exec na frente não é decoração. Ele garante que o Jekyll executado é o da versão que o Gemfile.lock fixou, e não outro que esteja no PATH.
Fazer o domínio apontar para a pasta _site
O site existe, mas ninguém o vê ainda, porque o domínio aponta para outra pasta. Dois caminhos:
Mudar a raiz de documentos do domínio
No cPanel, abra Domínios, encontre o domínio ou subdomínio e edite a raiz de documentos (document root) para o caminho completo da pasta gerada. No exemplo usado aqui: /home/SEU_USUARIO/jekyll_app/_site.
Salve e abra o domínio no navegador. Se aparecer a home do Jekyll, acabou.
Copiar o conteúdo de _site para public_html
Se o painel não deixa editar a raiz daquele domínio, copie o resultado do build para a pasta que o domínio já usa:
cp -r /home/SEU_USUARIO/jekyll_app/_site/. /home/SEU_USUARIO/public_html/
O /. no fim copia o conteúdo da pasta, não a pasta inteira. Risco real: isso sobrescreve arquivos de mesmo nome dentro de public_html. Se já existe site ali, faça backup antes.
Por que o CSS não carrega e os links internos dão 404
Se o site abre mas o CSS não carrega e os links internos dão 404, confira url e baseurl no _config.yml. Em hospedagem com domínio próprio, baseurl costuma ser vazio e url é o endereço completo do site, com https://. Quem veio do GitHub Pages quase sempre tem um baseurl com o nome do repositório sobrando ali. Corrija, rode o build de novo e copie de novo.
O que acontece quando você edita um post e esquece de rodar o build
Não existe magia aqui, e é importante aceitar isso antes de adotar o fluxo:
- Edite o arquivo Markdown ou o layout, pelo Gerenciador de Arquivos ou enviando por FTP para a Application root.
- Abra o Terminal, cole o comando de ativação do ambiente.
- Rode
bundle exec jekyll build. - Se você usa a Opção B, rode também o
cp -rpara atualizarpublic_html.
Enquanto o build não roda, o visitante continua vendo a versão anterior. Se isso te incomoda toda semana, o problema não é a hospedagem: é que Jekyll pressupõe um passo de build, e quem quer editar e ver no ar na hora provavelmente está melhor servido por um CMS.
| Situação | Precisa rodar o build? |
|---|---|
Editou um post em _posts |
Sim |
Mudou _config.yml |
Sim |
Trocou uma imagem dentro de _site direto |
Não, mas o próximo build sobrescreve a mudança |
| Instalou um plugin novo no Gemfile | Sim, e rode o Run Bundle Install antes |
Quando gerar o site na sua máquina e subir só o _site é a melhor escolha
Se você já tem o Jekyll rodando no seu computador, considere não instalar nada no servidor. Rode bundle exec jekyll build localmente e envie a pasta _site para public_html por FTP ou pelo Gerenciador de Arquivos.
Vantagens: nenhuma dependência de versão de Ruby no servidor, nenhum bundle install para falhar, nenhum consumo de CPU da hospedagem para gerar HTML. Desvantagem: você depende da sua máquina para publicar, e não consegue atualizar o site de um celular ou de um computador emprestado.
O caminho do Setup Ruby App vale a pena quando você quer publicar direto do servidor, quando o projeto é mantido por mais de uma pessoa, ou quando você quer disparar o build por SSH a partir de uma automação. Para um blog pessoal que você atualiza do mesmo notebook, o upload do _site resolve, e resolve com menos partes móveis.
Fonte do procedimento de criação da aplicação Ruby e do uso do botão Run Bundle Install: How to Create a Jekyll Ruby Application, documentação oficial do cPanel, consultada em 16 de outubro de 2026. Os nomes de pasta, usuário e caminhos usados aqui são exemplos: substitua pelos seus.
Referências
- Documentação oficial (cpanel) — How to Create a Jekyll Ruby Application. Consultado em 2026-10-16.