Déployer un site Hugo sur AWS S3 avec AWS CLI

Déployer un site statique Hugo sur AWS S3 en utilisant l’AWS CLI offre une solution robuste et évolutive pour héberger votre site web. Ce guide couvre l’ensemble du processus de déploiement, de la configuration initiale aux stratégies avancées d’automatisation et de gestion de cache.

Le déploiement avec l’AWS CLI devient une approche g-to depuis que la distribution Hugo a retiré la commande deploy du package standard. Voir à propos de extended et withdeploy dans Comment installer Ubuntu 24.04 et outils utiles si vous faites cela localement et souhaitez toujours appeler hugo deploy.

Prérequis

Avant de déployer votre site Hugo sur AWS S3, assurez-vous d’avoir :

• Un site Hugo prêt pour le déploiement (si vous avez besoin d’aide pour en créer un, consultez le guide de démarrage rapide de Hugo)
• Un compte AWS avec les autorisations appropriées
• AWS CLI installé et configuré
• Connaissances de base des opérations en ligne de commande

Construction de votre site Hugo

La première étape pour déployer votre site Hugo consiste à générer les fichiers statiques. Utilisez la Feuille de triche Hugo comme référence pour les commandes et options disponibles.

Construisez votre site avec des indicateurs d’optimisation :

hugo --gc --minify

L’indicateur --gc supprime les fichiers de cache inutilisés, tandis que --minify compresse votre HTML, CSS et JavaScript pour une performance optimale. Cela génère votre site statique dans le répertoire public/, que nous allons déployer sur S3.

Configuration de l’AWS CLI

Si vous n’avez pas encore configuré l’AWS CLI, exécutez :

aws configure

Vous serez invité à entrer :

• AWS Access Key ID : votre clé d’accès AWS
• AWS Secret Access Key : votre clé secrète
• Région par défaut : votre région AWS préférée (par exemple, us-east-1, ap-southeast-2)
• Format de sortie par défaut : json (recommandé)

Pour l’accès programmatique, assurez-vous que votre utilisateur IAM a les autorisations pour :

• s3:PutObject
• s3:GetObject
• s3:DeleteObject
• s3:ListBucket
• cloudfront:CreateInvalidation (si vous utilisez CloudFront)

Création et configuration du bucket S3

Créer le bucket

Créez votre bucket S3 en utilisant l’AWS CLI :

aws s3 mb s3://votre-nom-de-bucket --region us-east-1

Important : Choisissez un nom de bucket globalement unique. Si vous prévoyez d’utiliser le bucket pour l’hébergement de sites web, le nom du bucket doit correspondre à votre nom de domaine si vous utilisez un domaine personnalisé.

Configurer le bucket pour l’hébergement de sites web statiques

Activez l’hébergement de sites web statiques :

aws s3 website s3://votre-nom-de-bucket \
  --index-document index.html \
  --error-document 404.html

Définir la politique du bucket

Pour un accès en lecture publique (si vous n’utilisez pas CloudFront), créez une politique de bucket :

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

Appliquez la politique :

aws s3api put-bucket-policy \
  --bucket votre-nom-de-bucket \
  --policy file://bucket-policy.json

Note de sécurité : Si vous utilisez CloudFront (recommandé), vous pouvez restreindre l’accès au bucket S3 à CloudFront uniquement, éliminant ainsi la nécessité d’un accès en lecture publique.

Déploiement sur S3 en utilisant l’AWS CLI

La commande de déploiement principale utilise aws s3 sync pour télécharger votre site :

aws s3 sync public/ s3://votre-nom-de-bucket/ \
  --delete \
  --cache-control max-age=60

Paramètres clés expliqués

• public/ : votre répertoire de sortie local Hugo
• s3://votre-nom-de-bucket/ : votre destination de bucket S3
• --delete : supprime les fichiers dans S3 qui n’existent pas localement, assurant que votre bucket reflète votre build
• --cache-control max-age=60 : définit les en-têtes de cache (60 secondes dans cet exemple)

Options de synchronisation avancées

Pour plus de contrôle sur votre déploiement :

aws s3 sync public/ s3://votre-nom-de-bucket/ \
  --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"

Cet exemple définit différentes durées de cache pour les fichiers HTML (60 secondes) par rapport aux actifs statiques comme JavaScript (1 an), ce qui est une stratégie d’optimisation courante.

Configuration de la distribution CloudFront

Bien que S3 puisse héberger des sites web statiques directement, l’utilisation d’Amazon CloudFront en tant que CDN offre de meilleures performances, sécurité et distribution mondiale.

Créer une distribution CloudFront

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

Une configuration CloudFront de base inclut :

• Le bucket S3 en tant qu’origine
• Comportements de cache par défaut
• Certificat SSL/TLS (depuis AWS Certificate Manager)
• Configuration de domaine personnalisé (optionnel)

Stratégies de gestion de cache

Lors du déploiement via CloudFront, envisagez ces stratégies de mise en cache :

1. Définir le TTL maximal : Configurez le TTL maximal de CloudFront pour contrôler la durée pendant laquelle le contenu est mis en cache aux emplacements de bordure
2. Versionnage du contenu : Utilisez des identifiants de version dans les noms de fichiers (par exemple, style-v2.css) pour forcer les mises à jour de cache
3. En-têtes Cache-Control : Définissez des en-têtes appropriés lors de la synchronisation S3 (comme montré ci-dessus)
4. Invalidation sélective : Invalidez uniquement les chemins modifiés plutôt que l’ensemble du cache

Invalidation de cache

Après avoir déployé des mises à jour, invalidez le cache CloudFront pour servir du contenu frais :

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

Pour des invalidations plus ciblées :

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

Considération de coût : Les 1 000 chemins d’invalidation par mois sont gratuits. Au-delà, chaque chemin coûte 0,005 $. Utilisez une invalidation sélective pour minimiser les coûts.

Automatisation avec CI/CD

Les déploiements manuels fonctionnent pour les petits projets, mais l’automatisation est essentielle pour les flux de travail de production. Vous pouvez intégrer ce processus de déploiement avec Utilisation des actions Gitea pour déployer un site Hugo sur AWS S3 ou des pipelines CI/CD similaires.

Script de déploiement de base

Créez un script de déploiement simple :

#!/bin/bash
set -e

# Construire le site Hugo
echo "Construction du site Hugo..."
hugo --gc --minify

# Déployer sur S3
echo "Déploiement sur S3..."
aws s3 sync public/ s3://votre-nom-de-bucket/ \
  --delete \
  --cache-control max-age=60

# Invalider le cache CloudFront
echo "Invalidation du cache CloudFront..."
aws cloudfront create-invalidation \
  --distribution-id VOTRE_ID_DE_DISTRIBUTION \
  --paths "/*"

echo "Déploiement terminé !"

Rendez-le exécutable et exécutez :

chmod +x deploy.sh
./deploy.sh

Exemple GitHub Actions

Pour les dépôts GitHub, créez .github/workflows/deploy.yml :

name: Déployer sur AWS S3

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Configurer Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'

      - name: Construire
        run: hugo --gc --minify

      - name: Configurer les informations d'identification 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: Déployer sur S3
        run: |
          aws s3 sync public/ s3://votre-nom-de-bucket/ \
            --delete \
            --cache-control max-age=60          

      - name: Invalider CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/*"          

Surveillance et optimisation

Activer la journalisation

Configurez la journalisation S3 et CloudFront pour suivre les modèles d’accès :

# Activer la journalisation d'accès S3
aws s3api put-bucket-logging \
  --bucket votre-nom-de-bucket \
  --bucket-logging-status file://logging.json

Configurer des alarmes CloudWatch

Surveillez votre déploiement avec 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

Dépannage des problèmes courants

Fichiers non mis à jour

Si les modifications n’apparaissent pas :

1. Vérifiez l’état d’invalidation du cache CloudFront
2. Vérifiez que l’indicateur --delete est utilisé dans la commande de synchronisation
3. Videz le cache du navigateur ou testez en mode incognito
4. Vérifiez les autorisations du bucket S3

Déploiements lents

Optimisez les performances de synchronisation :

• Utilisez --exclude et --include pour sauter les fichiers inutiles
• Envisagez d’utiliser --size-only pour des comparaisons plus rapides
• Utilisez des téléchargements parallèles avec --cli-read-timeout et --cli-write-timeout

Erreurs de permission

Assurez-vous que votre utilisateur IAM a :

• Accès aux autorisations du bucket S3
• Autorisations d’invalidation CloudFront (le cas échéant)
• Politiques de bucket correctement configurées

Résumé des bonnes pratiques

1. Utilisez toujours --delete pour maintenir S3 en synchronisation avec votre build local
2. Définissez des en-têtes de cache appropriés en fonction des types de fichiers
3. Utilisez CloudFront pour les déploiements de production
4. Automatisez les déploiements avec des pipelines CI/CD
5. Surveillez les coûts - soyez conscient des frais d’invalidation CloudFront
6. Versionnez vos déploiements - étiquetez les versions pour un retour facile
7. Testez localement d’abord - vérifiez votre build Hugo avant de déployer

Ressources connexes

Pour plus d’informations détaillées sur le déploiement de Hugo, consultez le guide complet sur déployer un site généré par Hugo sur AWS S3, qui couvre des options et configurations de déploiement supplémentaires.

Lors de la rédaction de votre contenu, n’oubliez pas d’utiliser des blocs de code Markdown pour les exemples de code, et faites référence à la Feuille de triche Markdown complète pour les directives de formatage.

Liens utiles

• Déployer un site généré par Hugo sur AWS S3
• Utilisation des actions Gitea pour déployer un site Hugo sur AWS S3
• Feuille de triche Hugo
• Feuille de triche Markdown
• Utilisation des blocs de code Markdown

Références externes

• Documentation officielle d’AWS S3 pour l’hébergement de sites web statiques
• Référence des commandes AWS CLI pour S3
• Bonnes pratiques pour le contrôle du cache CloudFront
• Documentation officielle de Hugo
• Guide d’invalidation de CloudFront