Implementar un sitio de Hugo en AWS S3 con AWS CLI

Implementación de un sitio estático de Hugo en AWS S3 utilizando la CLI de AWS proporciona una solución robusta y escalable para alojar su sitio web. Esta guía cubre el proceso completo de implementación, desde la configuración inicial hasta estrategias de automatización avanzada y gestión de caché.

La implementación con la CLI de AWS se está convirtiendo en el enfoque g-to desde que la distribución de Hugo eliminó el comando deploy del paquete estándar. Vea sobre extended y withdeploy en Cómo instalar Ubuntu 24.04 y herramientas útiles si está haciendo esto localmente y aún quiere llamar a hugo deploy.

Requisitos previos

Antes de implementar su sitio de Hugo en AWS S3, asegúrese de tener:

• Un sitio de Hugo listo para la implementación (si necesita ayuda para crear uno, consulte la guía rápida de inicio de Hugo)
• Una cuenta de AWS con permisos adecuados
• La CLI de AWS instalada y configurada
• Conocimientos básicos de operaciones en línea de comandos

Construyendo su sitio de Hugo

El primer paso en la implementación de su sitio de Hugo es generar los archivos estáticos. Use la Hoja de trucos de Hugo como referencia sobre los comandos y opciones disponibles.

Construya su sitio con banderas de optimización:

hugo --gc --minify

La bandera --gc elimina archivos de caché no utilizados, mientras que --minify comprime su HTML, CSS y JavaScript para un rendimiento óptimo. Esto genera su sitio estático en el directorio public/, que es lo que implementaremos en S3.

Configurando la CLI de AWS

Si aún no ha configurado la CLI de AWS, ejecute:

aws configure

Se le pedirá que ingrese:

• AWS Access Key ID: Su clave de acceso de AWS
• AWS Secret Access Key: Su clave de acceso secreta
• Región predeterminada: Su región de AWS preferida (por ejemplo, us-east-1, ap-southeast-2)
• Formato de salida predeterminado: json (recomendado)

Para el acceso programático, asegúrese de que su usuario de IAM tenga permisos para:

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket
• cloudfront:CreateInvalidation (si está usando CloudFront)

Creando y configurando el bucket de S3

Crear el bucket

Cree su bucket de S3 usando la CLI de AWS:

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

Importante: Elija un nombre de bucket globalmente único. Si planea usar el bucket para alojar un sitio web, el nombre del bucket debe coincidir con su nombre de dominio si está usando un dominio personalizado.

Configurar el bucket para alojar sitios web estáticos

Habilite el alojamiento de sitios web estáticos:

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

Establecer la política del bucket

Para el acceso de lectura pública (si no está usando CloudFront), cree una 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 la política:

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

Nota de seguridad: Si está usando CloudFront (recomendado), puede restringir el acceso al bucket de S3 solo a CloudFront, eliminando la necesidad de acceso de lectura pública.

Implementando en S3 usando la CLI de AWS

El comando de implementación principal utiliza aws s3 sync para subir su sitio:

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

Explicación de parámetros clave

• public/: Su directorio local de salida de Hugo
• s3://your-bucket-name/: Su destino de bucket de S3
• --delete: Elimina archivos en S3 que no existen localmente, asegurando que su bucket se mire a sí mismo
• --cache-control max-age=60: Establece encabezados de caché (60 segundos en este ejemplo)

Opciones avanzadas de sincronización

Para un control más detallado sobre su implementación:

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 ejemplo establece diferentes duraciones de caché para archivos HTML (60 segundos) frente a activos estáticos como JavaScript (1 año), que es una estrategia de optimización común.

Configurando una distribución de CloudFront

Aunque S3 puede alojar sitios web estáticos directamente, usar Amazon CloudFront como CDN proporciona un mejor rendimiento, seguridad y distribución global.

Crear una distribución de CloudFront

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

Una configuración básica de CloudFront incluye:

• Bucket de S3 como origen
• Comportamientos de caché predeterminados
• Certificado SSL/TLS (de AWS Certificate Manager)
• Configuración de dominio personalizado (opcional)

Estrategias de gestión de caché

Al implementar a través de CloudFront, considere estas estrategias de caché:

1. Establecer TTL máximo: Configure el TTL máximo de CloudFront para controlar cuánto tiempo se almacena el contenido en ubicaciones de borde
2. Versionado de contenido: Use identificadores de versión en nombres de archivos (por ejemplo, style-v2.css) para forzar actualizaciones de caché
3. Encabezados de caché-control: Establezca encabezados adecuados durante la sincronización de S3 (como se mostró anteriormente)
4. Invalidación selectiva: Invalidar solo los caminos modificados en lugar de toda la caché

Invalidación de caché

Después de implementar actualizaciones, invalide la caché de CloudFront para servir contenido fresco:

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

Para invalidaciones más específicas:

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

Consideración de costos: Las primeras 1,000 rutas de invalidación por mes son gratuitas. Después de eso, cada ruta cuesta $0.005. Use la invalidación selectiva para minimizar costos.

Automatización con CI/CD

Las implementaciones manuales funcionan para proyectos pequeños, pero la automatización es esencial para flujos de trabajo de producción. Puede integrar este proceso de implementación con Acciones de Gitea para implementar un sitio web de Hugo en AWS S3 o pipelines de CI/CD similares.

Script básico de implementación

Cree un script de implementación simple:

#!/bin/bash
set -e

# Construir sitio de Hugo
echo "Construyendo sitio de Hugo..."
hugo --gc --minify

# Implementar en S3
echo "Implementando en S3..."
aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

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

echo "Implementación completa!"

Hágalo ejecutable y ejecute:

chmod +x deploy.sh
./deploy.sh

Ejemplo de GitHub Actions

Para repositorios de GitHub, cree .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: Configurar Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
      
      - name: Construir
        run: hugo --gc --minify
      
      - name: Configurar credenciales de AWS
        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: Implementar en S3
        run: |
          aws s3 sync public/ s3://your-bucket-name/ \
            --delete \
            --cache-control max-age=60          
      
      - name: Invalidar CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"          

Monitoreo y optimización

Habilitar registros

Configure el registro de S3 y CloudFront para rastrear patrones de acceso:

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

Configurar alarmas de CloudWatch

Monitoree su implementación con CloudWatch:

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

Solución de problemas de problemas comunes

Archivos que no se actualizan

Si los cambios no aparecen:

1. Verifique el estado de la invalidación de la caché de CloudFront
2. Verifique que se use la bandera --delete en el comando de sincronización
3. Limpie la caché del navegador o pruebe en modo incógnito
4. Verifique los permisos del bucket de S3

Implementaciones lentas

Optimice el rendimiento de la sincronización:

• Use --exclude y --include para omitir archivos innecesarios
• Considere usar --size-only para comparaciones más rápidas
• Use subidas paralelas con --cli-read-timeout y --cli-write-timeout

Errores de permisos

Asegúrese de que su usuario de IAM tenga:

• Permisos de acceso al bucket de S3
• Permisos de invalidación de CloudFront (si es aplicable)
• Políticas de bucket adecuadamente configuradas

Resumen de buenas prácticas

1. Siempre use --delete para mantener S3 sincronizado con su construcción local
2. Establezca encabezados de caché adecuados según los tipos de archivo
3. Use CloudFront para implementaciones de producción
4. Automatice las implementaciones con pipelines de CI/CD
5. Monitoree los costos - tenga en cuenta los cargos por invalidación de CloudFront
6. Versione sus implementaciones - etiquete las liberaciones para un fácil retroceso
7. Pruebe localmente primero - verifique su construcción de Hugo antes de implementar

Recursos relacionados

Para obtener información más detallada sobre la implementación de Hugo, consulte la guía completa sobre implementar un sitio web generado por Hugo en AWS S3, que cubre opciones y configuraciones de implementación adicionales.

Cuando escriba su contenido, recuerde usar los bloques de código de Markdown para ejemplos de código, y consulte la Hoja de trucos completa de Markdown para directrices de formato.

Enlaces útiles

• Implementar un sitio web generado por Hugo en AWS S3
• Usar Acciones de Gitea para implementar un sitio web de Hugo en AWS S3
• Hoja de trucos de Hugo
• Hoja de trucos de Markdown
• Usar bloques de código de Markdown

Referencias externas

• Documentación de alojamiento de sitios web estáticos de AWS S3
• Referencia de comandos S3 de la CLI de AWS
• Mejores prácticas de control de caché de CloudFront
• Documentación oficial de Hugo
• Guía de invalidación de CloudFront