Implante o site Hugo na AWS S3 com o AWS CLI

Automatize a implantação do Hugo no AWS S3

Conteúdo da página

A implantação de um site estático Hugo no AWS S3 usando a AWS CLI oferece uma solução robusta e escalável para hospedar seu site. Este guia cobre o processo completo de implantação, desde a configuração inicial até estratégias avançadas de automação e gerenciamento de cache.

Para um contexto mais amplo sobre tópicos de infraestrutura web, consulte o cluster de infraestrutura web.

tetris colorido na mesa

A implantação com a AWS CLI está se tornando a abordagem padrão, já que a distribuição do Hugo removeu o comando deploy do pacote padrão. Consulte sobre extended e withdeploy em Como Instalar Ubuntu 24.04 e ferramentas úteis se for fazer isso localmente e ainda quiser chamar hugo deploy.

Pré-requisitos

Antes de implantar seu site Hugo no AWS S3, certifique-se de ter:

  • Um site Hugo pronto para implantação (se precisar de ajuda para criar um, consulte o guia de início rápido do Hugo)
  • Uma conta AWS com permissões apropriadas
  • AWS CLI instalado e configurado
  • Conhecimento básico de operações de linha de comando

Construindo Seu Site Hugo

O primeiro passo para implantar seu site Hugo é gerar os arquivos estáticos. Use a Lista de Comandos do Hugo como referência para comandos e opções disponíveis.

Construa seu site com flags de otimização:

hugo --gc --minify

A flag --gc remove arquivos de cache não utilizados, enquanto --minify comprime seu HTML, CSS e JavaScript para desempenho ideal. Isso gera seu site estático no diretório public/, que é o que implantaremos no S3.

Configurando a AWS CLI

Se você ainda não configurou a AWS CLI, execute:

aws configure

Você será solicitado a inserir:

  • ID da Chave de Acesso AWS: Sua chave de acesso AWS
  • Chave Secreta de Acesso AWS: Sua chave secreta de acesso
  • Região padrão: Sua região AWS preferida (ex.: us-east-1, ap-southeast-2)
  • Formato de saída padrão: json (recomendado)

Para acesso programático, certifique-se de que seu usuário IAM tenha permissões para:

  • s3:PutObject
  • s3:GetObject
  • s3:DeleteObject
  • s3:ListBucket
  • cloudfront:CreateInvalidation (se estiver usando CloudFront)

Criando e Configurando o Bucket S3

Criar o Bucket

Crie seu bucket S3 usando a AWS CLI:

aws s3 mb s3://your-bucket-name --region us-east-1

Importante: Escolha um nome de bucket globalmente único. Se planeja usar o bucket para hospedagem de sites, o nome do bucket deve corresponder ao seu nome de domínio se estiver usando um domínio personalizado.

Configurar Bucket para Hospedagem de Sites Estáticos

Ative a hospedagem de sites estáticos:

aws s3 website s3://your-bucket-name \
  --index-document index.html \
  --error-document 404.html

Definir Política do Bucket

Para acesso de leitura pública (se não estiver usando CloudFront), crie uma política de bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::your-bucket-name/*"
    }
  ]
}

Aplique a política:

aws s3api put-bucket-policy \
  --bucket your-bucket-name \
  --policy file://bucket-policy.json

Nota de Segurança: Se estiver usando CloudFront (recomendado), você pode restringir o acesso ao bucket S3 apenas ao CloudFront, eliminando a necessidade de acesso de leitura pública.

Implantando no S3 Usando a AWS CLI

O comando central de implantação usa aws s3 sync para fazer upload do seu site:

aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

Parâmetros Chave Explicados

  • public/: Seu diretório de saída local do Hugo
  • s3://your-bucket-name/: Seu destino no bucket S3
  • --delete: Remove arquivos no S3 que não existem localmente, garantindo que seu bucket espelhe sua build
  • --cache-control max-age=60: Define os cabeçalhos de cache (60 segundos neste exemplo)

Opções Avançadas de Sincronização

Para ter mais controle sobre sua implantação:

aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control "public, max-age=31536000, immutable" \
  --exclude "*.html" \
  --cache-control "public, max-age=60" \
  --include "*.html" \
  --exclude "*.js" \
  --cache-control "public, max-age=31536000, immutable" \
  --include "*.js"

Este exemplo define durações de cache diferentes para arquivos HTML (60 segundos) versus ativos estáticos como JavaScript (1 ano), o que é uma estratégia de otimização comum.

Configurando Distribuição CloudFront

Embora o S3 possa hospedar sites estáticos diretamente, usar o Amazon CloudFront como CDN oferece melhor desempenho, segurança e distribuição global. Para configuração de preços pay-as-you-go (pagamento conforme o uso), consulte criando CloudFront com pagamento conforme o uso.

Criar Distribuição CloudFront

aws cloudfront create-distribution \
  --distribution-config file://cloudfront-config.json

Uma configuração básica do CloudFront inclui:

  • Bucket S3 como origem
  • Comportamentos de cache padrão
  • Certificado SSL/TLS (do AWS Certificate Manager)
  • Configuração de domínio personalizado (opcional)

Estratégias de Gerenciamento de Cache

Ao implantar através do CloudFront, considere estas estratégias de cache:

  1. Definir TTL Máximo: Configure o TTL Máximo do CloudFront para controlar por quanto tempo o conteúdo é armazenado em cache nas localizações de borda
  2. Versionamento de Conteúdo: Use identificadores de versão nos nomes de arquivos (ex.: style-v2.css) para forçar atualizações de cache
  3. Cabeçalhos Cache-Control: Defina cabeçalhos apropriados durante a sincronização S3 (como mostrado acima)
  4. Invalidação Seletiva: Invalidar apenas os caminhos alterados em vez de todo o cache

Invalidação de Cache

Após implantar atualizações, invalide o cache do CloudFront para servir conteúdo fresco:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

Para invalidações mais direcionadas:

aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/index.html" "/blog/*"

Consideração de Custo: Os primeiros 1.000 caminhos de invalidação por mês são gratuitos. Depois disso, cada caminho custa $0,005. Use invalidação seletiva para minimizar custos.

Automação com CI/CD

Implantações manuais funcionam para projetos pequenos, mas a automação é essencial para fluxos de trabalho de produção. Você pode integrar este processo de implantação com Gitea Actions para implantar site Hugo no AWS S3 ou pipelines CI/CD similares.

Script de Implantação Básico

Crie um script de implantação simples:

#!/bin/bash
set -e

# Construir site Hugo
echo "Construindo site Hugo..."
hugo --gc --minify

# Implantar no S3
echo "Implantando no S3..."
aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

# Invalidar cache CloudFront
echo "Invalidando cache CloudFront..."
aws cloudfront create-invalidation \
  --distribution-id YOUR_DISTRIBUTION_ID \
  --paths "/*"

echo "Implantação concluída!"

Torne-o executável e rode:

chmod +x deploy.sh
./deploy.sh

Exemplo de GitHub Actions

Para repositórios do GitHub, crie .github/workflows/deploy.yml:

name: Deploy to AWS S3

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      
      - name: Build
        run: hugo --gc --minify
      
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1
      
      - name: Deploy to S3
        run: |
          aws s3 sync public/ s3://your-bucket-name/ \
            --delete \
            --cache-control max-age=60          
      
      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"

Monitoramento e Otimização

Habilitar Logs

Configure logs do S3 e CloudFront para rastrear padrões de acesso:

# Habilitar logs de acesso S3
aws s3api put-bucket-logging \
  --bucket your-bucket-name \
  --bucket-logging-status file://logging.json

Configurar Alarmes CloudWatch

Monitore sua implantação com CloudWatch:

aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate \
  --alarm-description "Alerta sobre alta taxa de erros" \
  --metric-name 4xxError \
  --namespace AWS/CloudFront \
  --statistic Sum \
  --period 300 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold

Solução de Problemas Comuns

Arquivos Não Atualizando

Se as alterações não estiverem aparecendo:

  1. Verifique o status da invalidação do cache CloudFront
  2. Confirme que a flag --delete está sendo usada no comando de sincronização
  3. Limpe o cache do navegador ou teste no modo anônimo
  4. Verifique as permissões do bucket S3

Implantações Lentas

Otimize o desempenho da sincronização:

  • Use --exclude e --include para pular arquivos desnecessários
  • Considere usar --size-only para comparações mais rápidas
  • Use uploads paralelos com --cli-read-timeout e --cli-write-timeout

Erros de Permissão

Certifique-se de que seu usuário IAM tenha:

  • Permissões de acesso ao bucket S3
  • Permissões de invalidação do CloudFront (se aplicável)
  • Políticas de bucket configuradas corretamente

Resumo das Melhores Práticas

  1. Sempre use --delete para manter o S3 sincronizado com sua build local
  2. Defina cabeçalhos de cache apropriados com base nos tipos de arquivo
  3. Use CloudFront para implantações de produção
  4. Automatize implantações com pipelines CI/CD
  5. Monitore custos - esteja atento às cobranças de invalidação do CloudFront
  6. Versione suas implantações - marque releases para rollback fácil
  7. Teste localmente primeiro - verifique sua build do Hugo antes de implantar

Recursos Relacionados

Para informações mais detalhadas sobre implantação do Hugo, consulte o guia abrangente sobre implantar site gerado pelo Hugo no AWS S3, que cobre opções adicionais de implantação e configurações.

Ao escrever seu conteúdo, lembre-se de usar blocos de código Markdown para exemplos de código e consulte a Lista de Comandos Markdown Abrangente para diretrizes de formatação.

Referências Externas

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.