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

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

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

---

## 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](https://docs.cpanel.net/knowledge-base/web-services/how-to-create-a-jekyll-ruby-application/) 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 build` outra vez, o `_site` continua 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.rb` que 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):

```ruby
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 `Gemfile` está na raiz da aplicação, não dentro de uma subpasta. É o erro mais comum quando a pessoa sobe um `.zip` e 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:

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

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

```bash
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 -r` para atualizar `public_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](https://docs.cpanel.net/knowledge-base/web-services/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.

