Come si distribuisce un sito Hugo su AWS S3 utilizzando AWS CLI?

Costruisci il tuo sito Hugo con hugo --gc --minify , configura le credenziali AWS CLI, crea un bucket S3, quindi sincronizza la tua cartella public/ con S3 utilizzando aws s3 sync public/ s3://your-bucket-name/ --delete --cache-control max-age=60 .

Quali sono le migliori pratiche per il caching durante il deployment su S3?

Impostare gli header Cache-Control appropriati durante la sincronizzazione (es. --cache-control max-age=60 ), configurare i valori Maximum TTL di CloudFront e utilizzare l’invalidazione del cache per aggiornamenti immediati. Considerare la versionatura del contenuto per gli asset critici.

Come annullare il cache di CloudFront dopo il deployment?

Utilizzare aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID --paths "/*" per invalidare l’intero cache, oppure specificare percorsi particolari. Le prime 1.000 invalidazioni al mese sono gratuite.

È possibile automatizzare il deployment di Hugo su AWS S3?

Sì, è possibile automatizzare i deployment utilizzando pipeline CI/CD come GitHub Actions, Gitea Actions o AWS CodePipeline. Queste possono costruire il tuo sito Hugo e deployarlo automaticamente su commit del codice.

Qual è la differenza tra l’hosting di siti web su S3 e CloudFront?

L’hosting di siti web su S3 fornisce un hosting statico di base, mentre CloudFront è una CDN che memorizza in cache il contenuto in punti di accesso distribuiti in tutto il mondo, migliorando le prestazioni e riducendo la latenza. CloudFront fornisce inoltre la terminazione SSL/TLS e funzionalità di sicurezza più avanzate.

Distribuire un sito Hugo su AWS S3 con AWS CLI

Automatizzare il deployment di Hugo su AWS S3

Indice

Deploying a Hugo static site to AWS S3 utilizzando l’AWS CLI fornisce una soluzione robusta e scalabile per ospitare il tuo sito web. Questa guida copre l’intero processo di deployment, dall’impostazione iniziale alle strategie di automazione avanzata e gestione del cache.

colour tetris on the table

Il deployment con l’AWS CLI sta diventando un approccio g-to da quando la distribuzione di Hugo ha rimosso il comando deploy dal pacchetto standard. Vedere extended e withdeploy in How to Install Ubuntu 24.04 & useful tools se si sta eseguendo questo localmente e si desidera comunque chiamare hugo deploy.

Prerequisiti

Prima di deployare il tuo sito Hugo su AWS S3, assicurati di avere:

Un sito Hugo pronto per il deployment (se hai bisogno di aiuto per crearne uno, consulta la Hugo quickstart guide)
Un account AWS con le autorizzazioni appropriate
AWS CLI installato e configurato
Conoscenza di base delle operazioni a riga di comando

Costruendo il tuo sito Hugo

Il primo passo nel deployare il tuo sito Hugo è generare i file statici. Utilizza la Hugo Cheat Sheet come riferimento per i comandi e le opzioni disponibili.

Costruisci il tuo sito con i flag di ottimizzazione:

hugo --gc --minify

Il flag --gc rimuove i file di cache non utilizzati, mentre --minify comprime il tuo HTML, CSS e JavaScript per un’ottima prestazione. Questo genera il tuo sito statico nella directory public/, che deployeremo su S3.

Configurazione dell’AWS CLI

Se non hai ancora configurato l’AWS CLI, esegui:

aws configure

Ti verrà chiesto di inserire:

AWS Access Key ID: La tua chiave di accesso AWS
AWS Secret Access Key: La tua chiave segreta di accesso AWS
Default region: La tua regione preferita AWS (es. us-east-1, ap-southeast-2)
Default output format: json (consigliato)

Per l’accesso programmabile, assicurati che l’utente IAM abbia le autorizzazioni per:

s3:PutObject
s3:GetObject
s3:DeleteObject
s3:ListBucket
cloudfront:CreateInvalidation (se si utilizza CloudFront)

Creare e configurare il bucket S3

Creare il bucket

Crea il tuo bucket S3 utilizzando l’AWS CLI:

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

Importante: Scegli un nome del bucket globalmente unico. Se hai intenzione di utilizzare il bucket per l’hosting del sito web, il nome del bucket deve corrispondere al nome del tuo dominio se stai utilizzando un dominio personalizzato.

Configurare il bucket per l’hosting statico del sito web

Abilita l’hosting statico del sito web:

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

Impostare la politica del bucket

Per l’accesso in lettura pubblica (se non si utilizza CloudFront), crea una politica del bucket:

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

Applica la politica:

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

Nota sulla sicurezza: Se si utilizza CloudFront (consigliato), è possibile limitare l’accesso al bucket S3 a CloudFront solo, eliminando la necessità di accesso in lettura pubblica.

Deployare su S3 utilizzando l’AWS CLI

Il comando principale di deploy utilizza aws s3 sync per caricare il tuo sito:

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

Parametri chiave spiegati

public/: La tua directory locale di output di Hugo
s3://your-bucket-name/: La destinazione del tuo bucket S3
--delete: Rimuove i file in S3 che non esistono localmente, assicurando che il bucket specchi il tuo build
--cache-control max-age=60: Imposta gli header del cache (60 secondi in questo esempio)

Opzioni avanzate di sincronizzazione

Per un controllo maggiore sul tuo deployment:

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"

Questo esempio imposta durate diverse del cache per i file HTML (60 secondi) rispetto agli asset statici come JavaScript (1 anno), che è una strategia comune di ottimizzazione.

Configurazione di una distribuzione CloudFront

Sebbene S3 possa ospitare direttamente siti web statici, l’utilizzo di Amazon CloudFront come CDN fornisce prestazioni migliori, maggiore sicurezza e una distribuzione globale.

Creare una distribuzione CloudFront

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

Una configurazione base di CloudFront include:

Il bucket S3 come origine
Comportamenti di cache predefiniti
Certificato SSL/TLS (da AWS Certificate Manager)
Configurazione del dominio personalizzato (opzionale)

Strategie di gestione del cache

Durante il deployment tramite CloudFront, considera queste strategie di caching:

Impostare la TTL massima: Configura la TTL massima di CloudFront per controllare quanto a lungo il contenuto viene memorizzato nelle località di edge
Versioning del contenuto: Utilizza identificatori di versione nei nomi dei file (es. style-v2.css) per forzare gli aggiornamenti del cache
Header di cache-control: Imposta gli header appropriati durante la sincronizzazione S3 (come mostrato sopra)
Invalidazione selettiva: Invalida solo i percorsi modificati invece di tutto il cache

Invalidazione del cache

Dopo aver deployato gli aggiornamenti, invalida il cache di CloudFront per servire il contenuto fresco:

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

Per invalidazioni mirate:

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

Considerazione dei costi: Le prime 1.000 vie di invalidazione al mese sono gratuite. Dopo, ogni via costa $0,005. Utilizza l’invalidazione mirata per minimizzare i costi.

Automazione con CI/CD

I deploy manuali funzionano per progetti piccoli, ma l’automazione è essenziale per i flussi di lavoro di produzione. Puoi integrare questo processo di deployment con Gitea Actions to deploy Hugo website to AWS S3 o pipeline CI/CD simili.

Script di deployment base

Crea uno script di deployment semplice:

#!/bin/bash
set -e

# Build Hugo site
echo "Building Hugo site..."
hugo --gc --minify

# Deploy to S3
echo "Deploying to S3..."
aws s3 sync public/ s3://your-bucket-name/ \
  --delete \
  --cache-control max-age=60

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

echo "Deployment complete!"

Rendi eseguibile e esegui:

chmod +x deploy.sh
./deploy.sh

Esempio di GitHub Actions

Per i repository GitHub, crea .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 "/*"

Monitoraggio e ottimizzazione

Abilitare i log

Configura i log di S3 e CloudFront per tracciare i pattern di accesso:

# Enable S3 access logging
aws s3api put-bucket-logging \
  --bucket your-bucket-name \
  --bucket-logging-status file://logging.json

Configurare allarmi di CloudWatch

Monitora il tuo deployment con CloudWatch:

aws cloudwatch put-metric-alarm \
  --alarm-name high-error-rate \
  --alarm-description "Alert on high error rate" \
  --metric-name 4xxError \
  --namespace AWS/CloudFront \
  --statistic Sum \
  --period 300 \
  --threshold 10 \
  --comparison-operator GreaterThanThreshold

Risoluzione dei problemi comuni

I file non vengono aggiornati

Se i cambiamenti non appaiono:

Controlla lo stato dell’invalidazione del cache di CloudFront
Verifica che il flag --delete venga utilizzato nel comando di sincronizzazione
Pulisci la cache del browser o testa in modalità incognito
Controlla le autorizzazioni del bucket S3

Deployment lenti

Ottimizza le prestazioni della sincronizzazione:

Utilizza --exclude e --include per saltare i file non necessari
Considera l’uso di --size-only per confronti più veloci
Utilizza upload paralleli con --cli-read-timeout e --cli-write-timeout

Errori di autorizzazione

Assicurati che l’utente IAM abbia:

Autorizzazioni per l’accesso al bucket S3
Autorizzazioni per l’invalidazione di CloudFront (se applicabile)
Politiche del bucket correttamente configurate

Riepilogo delle best practice

Utilizza sempre --delete per mantenere S3 sincronizzato con il tuo build locale
Imposta gli header del cache appropriati in base ai tipi di file
Utilizza CloudFront per i deployment in produzione
Automatizza i deployment con pipeline CI/CD
Monitora i costi - sii consapevole delle tariffe di invalidazione di CloudFront
Versiona i deployment - etichetta le release per un facile rollback
Testa localmente prima - verifica il tuo build Hugo prima di deployare

Risorse correlate

Per ulteriori informazioni dettagliate sul deployment di Hugo, consulta la guida completa su deploying Hugo-generated website to AWS S3, che copre ulteriori opzioni e configurazioni di deployment.

Quando stai scrivendo il tuo contenuto, ricorda di utilizzare i corretti Markdown code blocks per gli esempi di codice e consulta la Comprehensive Markdown Cheatsheet per le linee guida di formattazione.