Implante o Site Hugo no AWS S3 com o AWS CLI

Automatize o implantação do Hugo no AWS S3

Conteúdo da página

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

tetris colorido na mesa

A implantação com a AWS CLI está se tornando uma abordagem g-to desde que a distribuição Hugo tenha removido o comando deploy do pacote padrão. Veja sobre extended e withdeploy em Como instalar o Ubuntu 24.04 & ferramentas úteis se estiver fazendo 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 criá-lo, consulte o Guia rápido do Hugo)
  • Uma conta AWS com permissões apropriadas
  • A AWS CLI instalada e configurada
  • Conhecimento básico sobre operações de linha de comando

Construindo seu site Hugo

A primeira etapa na implantação do seu site Hugo é gerar os arquivos estáticos. Use o Dicionário de atalhos do Hugo como referência para os comandos e opções disponíveis.

Construa seu site com bandeiras de otimização:

hugo --gc --minify

A bandeira --gc remove arquivos de cache não utilizados, enquanto --minify compacta seu HTML, CSS e JavaScript para um desempenho ideal. Isso gera seu site estático na pasta 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:

  • AWS Access Key ID: Sua chave de acesso AWS
  • AWS Secret Access Key: Sua chave secreta de acesso AWS
  • Região padrão: Sua região preferida da AWS (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 planejar usar o bucket para hospedagem de site, o nome do bucket deve corresponder ao nome do seu domínio se estiver usando um domínio personalizado.

Configurar o bucket para hospedagem de site estático

Ative a hospedagem de site estático:

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

Definir política do bucket

Para acesso público de leitura (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/*"
    }
  ]
}

Aplicar 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 público.

Implantando no S3 usando a AWS CLI

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

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

Parâmetros-chave explicados

  • public/: Seu diretório local de saída 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 construção
  • --cache-control max-age=60: Define cabeçalhos de cache (60 segundos neste exemplo)

Opções avançadas de sincronização

Para 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 diferentes durações de cache para arquivos HTML (60 segundos) versus ativos estáticos como JavaScript (1 ano), que é uma estratégia comum de otimização.

Configurando a distribuição CloudFront

Embora o S3 possa hospedar diretamente sites estáticos, usar o Amazon CloudFront como um CDN oferece melhor desempenho, segurança e distribuição global.

Criar a 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 essas estratégias de cache:

  1. Definir TTL máximo: Configure o TTL máximo do CloudFront para controlar quanto tempo o conteúdo é armazenado em locais 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 de 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: As primeiras 1.000 caminhos de invalidação por mês são gratuitas. Após isso, cada caminho custa $0,005. Use a invalidação seletiva para minimizar custos.

Automatizaçã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 Ações do Gitea para implantar um site Hugo no AWS S3 ou pipelines de CI/CD similares.

Script básico de implantação

Crie um script simples de implantação:

#!/bin/bash
set -e

# Construa o site Hugo
echo "Construindo o site Hugo..."
hugo --gc --minify

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

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

echo "Implantação completa!"

Torne-o executável e execute:

chmod +x deploy.sh
./deploy.sh

Exemplo de ações do GitHub

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

Ativar logs

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

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

Configurar alarmes do CloudWatch

Monitore sua implantação com o CloudWatch:

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

Solução de problemas comuns

Arquivos não atualizados

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

  1. Verifique o status da invalidação do cache do CloudFront
  2. Verifique se a bandeira --delete está sendo usada no comando de sincronização
  3. Limpe o cache do navegador ou teste no modo incógnito
  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 apropriadas configuradas

Resumo das melhores práticas

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

Recursos relacionados

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

Ao escrever seu conteúdo, lembre-se de usar os blocos de código Markdown para exemplos de código e consulte o Dicionário Completo de Markdown para diretrizes de formatação.

Referências Externas