Como criar um site estático utilizando HUGO no 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:
- Hugo — https://gohugo.io/getting-started/installing/
- Conta no Heroku — https://id.heroku.com/login
- CLI Heroku — https://devcenter.heroku.com/articles/heroku-cli#install-the-heroku-cli
- Conta GitHub** — https://github.com/
- CLI Git — https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
- Docker — https://docs.docker.com/engine/install/
Passos
- Criar um novo site pelo HUGO
- Associar ao GitHub**
- Criar app no Heroku
- Baixar um tema do Hugo e alterar o config.toml
- Criar os arquivos Dockerfile e heroku.yml
- Testar o HUGO localmente**
- Commitar as mudanças
- Subir a imagem para o Heroku
- Push das mudanças
- 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:
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.
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.
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:
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.
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.
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.
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.
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.
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”.
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).
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.
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.
