Trace install tas - Hugo

Objectif

Déployer un site statique simple à maintenir avec Hugo, servi localement par Podman puis exposé par le reverse proxy Caddy.

L'objectif est d'obtenir :

une maintenance faible
un contenu rédigé en Markdown
une publication reproductible
un rollback simple

Choix techniques retenus

Générateur statique : Hugo
Build : conteneur `docker.io/klakegg/hugo:ext-alpine`
Service HTTP : conteneur `docker.io/library/nginx:alpine`
Orchestration locale : Podman rootless + service utilisateur
Port local : `8100`
Exposition publique prévue :
- `hugo.lololand.org`
- `https://lololand.hopto.org:25700`
Répertoire projet : `/home/loic/sites/hugo-docs`

Arborescence

/home/loic/sites/hugo-docs/
├── content/
├── layouts/
├── public/
├── hugo.toml
└── publish.sh

Fichiers importants

Sources Hugo : `/home/loic/sites/hugo-docs`
Site généré : `/home/loic/sites/hugo-docs/public`
Service Podman user : `/home/loic/.config/containers/systemd/hugo-docs.container`

Principe de fonctionnement

Le contenu est rédigé dans le projet Hugo, puis généré en fichiers statiques dans le dossier `public/`.

Le service Podman ne génère pas le site lui-même :

Hugo produit les fichiers statiques
nginx sert ensuite le dossier `public/`

Cette séparation simplifie :

la maintenance
le diagnostic
le rollback
la reproductibilité

Publication

Générer le site

cd /home/loic/sites/hugo-docs
./publish.sh

Redémarrer le service

systemctl --user restart hugo-docs.service

Vérifier localement

curl -I http://127.0.0.1:8100

Service Podman

Le service utilisateur repose sur le fichier :

/home/loic/.config/containers/systemd/hugo-docs.container

Principe :

image `nginx:alpine`
montage en lecture seule du dossier `public/`
exposition locale sur le port `8100`
redémarrage automatique du service

Reverse proxy Caddy

Bloc prévu dans `/etc/caddy/Caddyfile` :

# Hugo docs
hugo.lololand.org:443 {
    import common_acme
    reverse_proxy 127.0.0.1:8100
}

# Hugo docs (accès port dédié de secours)
https://lololand.hopto.org:25700 {
    import common_acme
    reverse_proxy 127.0.0.1:8100
}

Utilisation courante

Ajouter une page

Créer un fichier Markdown dans `content/`.

Exemple :

cd /home/loic/sites/hugo-docs
mkdir -p content/docs
cat > content/docs/bonjour.md <<'EOF'
---
title: "Bonjour"
---

# Bonjour

Première page de test.
EOF

Regénérer le site

cd /home/loic/sites/hugo-docs
./publish.sh
systemctl --user restart hugo-docs.service

Avantages du choix Hugo

pas de base de données
pas d'application dynamique à maintenir
contenu lisible en texte brut
publication très rapide
très bon couplage avec git
rollback facile en restaurant les sources ou le rendu généré

Points d'attention

toute modification du contenu nécessite une régénération du site
le reverse proxy Caddy doit être configuré séparément
il faut conserver une sauvegarde du `Caddyfile` avant modification
le dossier `public/` ne doit pas être modifié manuellement

Rollback

En cas de problème :

restaurer la sauvegarde du `Caddyfile`
corriger ou restaurer le projet Hugo
régénérer le site
redémarrer `hugo-docs.service`
recharger `caddy`

Commandes utiles

cd /home/loic/sites/hugo-docs
./publish.sh
systemctl --user status hugo-docs.service
systemctl --user restart hugo-docs.service
curl -I http://127.0.0.1:8100

Résultat attendu

Une chaîne simple et maintenable :

édition en Markdown
génération statique via Hugo
service local via Podman
exposition publique via Caddy