Como criar um site estático utilizando HUGO no Heroku

Logos do HUGO e Heroku.

Intro

Recentemente descobri o HUGO (https://gohugo.io/), um gerador de sites estáticos, escrito em Go e de fácil utilização. A grande vantagem de utilizar o HUGO é a velocidade e praticidade para criar sites e blogs pessoais.

Com o site gerado, vem a pergunta, onde hospedar? Aí que entra o Heroku (https://www.heroku.com/), um serviço de hospedagem de aplicações, em nuvem. O mais interessante dessa plataforma é que ela oferece entre 550–1,000 horas* de hospedagem grátis por mês, ou seja, não será necessário pagar para hospedar seu site.

Atualmente o Heroku não suporta o uso direto do HUGO, então para contornar esse problema, iremos criar uma imagem Docker com as configurações necessárias para que ele seja inicializado pelo Heroku.

Pré requisitos

Para realizar este tutorial, você precisará de:

Passos

  1. Criar um novo site pelo HUGO
  2. Associar ao GitHub**
  3. Criar app no Heroku
  4. Baixar um tema do Hugo e alterar o config.toml
  5. Criar os arquivos Dockerfile e heroku.yml
  6. Testar o HUGO localmente**
  7. Commitar as mudanças
  8. Subir a imagem para o Heroku
  9. Push das mudanças
  10. Acesso ao site

BONUS — Uso de domínio personalizado com SSL

Hands-On

1. Criar um novo site pelo HUGO

Primeiramente iremos criar um novo site pela linha de comando (command-line interface — CLI).

Abra o terminal do seu computador (cmd no windows, terminal no linux e mac) e vá para a pasta em que gostaria de criar seu site.

No meu caso, irei criar na pasta Documents.

Comandos:

Resposta do comando hugo new site myhugosite.

2. Associar ao GitHub**

Na pasta criada pelo HUGO, inicializar o git e associar ao repositório no GitHub, necessário criar antes de adicionar o remote.

Exemplo de como criar repositório no github.

3. Criar app no Heroku

Para criar um app no Heroku, podemos utilizar tanto a interface gráfica quanto o CLI, neste caso, estou usando o CLI por ser mais simples. Tendo criado a conta no Heroku e instalado o CLI, basta inserir os comandos abaixo.

Resposta do comando heroku apps:create myhugosite.

Observe que estou me logando no Heroku, criando um app de nome myhugosite e associando ao repositório que o Heroku nos disponibiliza.

4. Baixar um tema do Hugo e alterar o config.toml

Nesse passo, a sua pasta deve estar com a seguinte estrutura:

Estrutura do site criado pelo Hugo.

Caso não tenha realizado o passo 2, a diferença é que não terá os arquivos README.md e .gitignore.

Para esse tutorial, utilizaremos o tema hugo-cohub, para escolher outros temas, basta visitar os sites https://jamstackthemes.dev/#ssg=hugo ou https://themes.gohugo.io/

Pelo padrão do HUGO, os temas devem estar clonados na pasta themes, por isso estou passando o caminho themes/hugo-cohub. Observe que estou removendo o .git do repositório clonado, faço isso apenas para não ficar com referências de outros projetos.

Agora, vamos alterar o arquivo config.toml para o nosso projeto. Observe os campos baseURL e theme. Esses são importantes para o uso correto do tema, o primeiro refere à url gerada pelo heroku, o padrão é https://<nomedoapp>.herokuapp.com, neste caso a url é https://myhugosite.herokuapp.com. O segundo refere-se ao nome da pasta onde o tema se encontra, no caso é hugo-cohub (não precisa referenciar a pasta themes). As outras configurações são auto-explicativas.

5. Criar os arquivos Dockerfile e heroku.yml

Iremos agora criar um arquivo chamado Dockerfile na raiz da pasta do projeto.

Dockerfile

Explicando: Estou utilizando a imagem debian:stable-slim, copiando todos os meus arquivos da pasta local (.) para a pasta /src. Após a cópia, inicio a instalação do hugo, limpo os arquivos desnecessários, crio o usuário hugo, utilizo o caminho /src como default do container e inicializo o Hugo.

O próximo passo é criar o heroku.yml, este é o arquivo que a plataforma irá se basear para executar as etapas de build e run. A documentação de como escrever um heroku.yml está disponível em:

https://devcenter.heroku.com/articles/build-docker-images-heroku-yml.

heroku.yml

Explicando: O primeiro passo a ser executado é o build da imagem conforme o Dockerfile, damos o nome da imagem gerada de web. Na próxima etapa, de run, falamos para executar o comando na imagem web.

Argumentos:

bind=0.0.0.0 → Associa a interface de conexão para o servidor (default “127.0.0.1”), se não colocar na “0.0.0.0” o Heroku não conseguirá acessar o servidor.

port=$PORT → O Heroku associa uma porta aleatória para seu Dyno, mas disponibiliza esse valor como variável de ambiente (default “1313”).

appendPort=false → Caso não mude para false, as referências dos links virão com o número da porta, causando erro no direcionamento e acesso de links (default “true”).

baseURL=https://myhugosite.herokuapp.com/ → hostname (e caminho) para a raiz do seu projeto, como estamos utilizando o Heroku, precismos atualizar conforme a URL que ele nos oferece.

Estrutura de arquivos.

6. Testar o HUGO localmente**

Para testar localmente iremos copiar os conteúdos das pastas do tema hugo-cohub/exampleSite para as pastas da estrutura gerada pelo Hugo. Após a cópia, basta iniciar o servidor com o comando hugo server.

Se tudo ocorrer bem, será possível acessar seu site localmente pelo endereço http://localhost:1313/

7. Commitar as mudanças

8. Subir a imagem para o Heroku

Conforme a documentação do heroku, para subir o container para o registry do Heroku, bastar realizarmos os comandos abaixo:

9. Push das mudanças

Para realizar mudanças em seu site, basta salvar as mudanças localmente, commitar e realizar um push para o Heroku.

Caso realizou o passo 2, podemos configurar o Heroku para realizar os deploys para cada push que realizar em uma branch.

Configuração do deploy pelo GitHub.
Habilitando o deploy automático para a branch main.

10. Acesso ao site

Para acessar o site basta esperar o build e deploy e acessar o link gerado pelo Heroku (https://<nomedoapp>.herokuapp.com) ou clickar no botão “Open app” na página Overview de seu app.

Página Overview do app no Heroku.

BONUS — Uso de domínio personalizado com SSL

1. Compra do domíno

É possível utilizar domínios de vários registradores, um exemplo famoso é o GoDaddy, onde oferece domínios de vários tipos.

2. Configuração do DNS do domínio

Primeiro precisaremos adicionar um domínio pela aba Settings do seu app no Heroku, botão “Add domain”.

Configuração de domínio na aba Settings.

Agora basta copiar o “DNS Target” gerado e alterar o valor do CNAME nas configurações do DNS do seu domínio (GoDaddy por exemplo).

Configuração do DNS no registrador (GoGaddy).

IMPORTANTE! → Ainda nas configurações de DNS, configurar o Encaminhamento ou Forwarding do tipo permanente (301) para o endereço do seu domínio, por exemplo: http://myhugosite.com ou https://myhugosite.com caso realize o passo 4.

3. Alteração do config.toml e heroku.yml

Nos arquivos config.toml e heroku.yml alterar o valor de baseURL para o nome do seu domínio, por exemplo baseURL = ‘http://myhugosite.com/’ ou https://myhugosite.com/ caso realize o passo 4.

4. Upgrade do Dyno para Hobby*** (7$ mensais).

Para fazer o upgrade é necessário cadastrar seu cartão de crédito em Account Settings → Billing. Após configurar, basta alterar o plano do Dyno pela aba Resources do seu app de Free para Hobby.

Para habilitar o SSL é só selecionar “Automatic Certificate Management” (ACM) nas configurações de certificado.

Configuração de SSL.

Considerações

* https://devcenter.heroku.com/articles/free-dyno-hours#dyno-sleeping
** Opcional
*** Somente caso queira SSL (HTTPS). Caso não se importe com o endereço HTTP, não precisa alterar o plano.

--

--

Data scientist and devops enthusiast.

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store