Son projet Hugo dans Coolify

Démarche à suivre dans l'ordre, pour héberger un Portfolio créé avec Hugo dans Coolify.

Pour créer le Portfolio lui-même, voir le tutoriel Créer son Portfolio avec Hugo.

Étapes à suivre par l'étudiant :
- A) Adapter le projet Hugo
- B) Pousser les modifications sur GitHub
- MAJ du projet par l'étudiant
Étapes à suivre par l'enseignant :
- C) Créer la ressource dans Coolify
- D) Déployer
- MAJ du projet par l'enseignant

Ce qui change par rapport à un projet Symfony

Un site Hugo est statique : une fois construit, il ne reste que des fichiers HTML, CSS et JavaScript. Il n'y a donc ni base de données, ni variable d'environnement secrète, ni migration à gérer. Le conteneur se compose de deux temps :

Construire le site avec Hugo (commande hugo, qui produit le dossier public/).
Servir ce dossier avec un serveur Web léger (Nginx).

A) Adapter le projet Hugo

1. Le thème doit faire partie du dépôt

Dans le tutoriel Hugo, le thème est récupéré avec git clone dans le dossier themes/. Or un dossier cloné contient son propre dossier .git : Git le traite alors comme un autre dépôt et n'envoie pas ses fichiers sur GitHub. Coolify construirait alors le site sans thème.

Supprimer le dossier .git du thème (exemple avec le thème ananke) :

Sous macOS, Linux ou Git Bash :
```
rm -rf themes/ananke/.git
```

Sous Windows (PowerShell) :

Remove-Item -Recurse -Force themes\ananke\.git

Explications :

Après cette suppression, les fichiers du thème sont de simples fichiers du projet : ils seront envoyés sur GitHub avec le reste.
Si un git add . a déjà été exécuté avant cette suppression, git status affiche themes/ananke comme un élément particulier (embedded git repository). Dans ce cas, après avoir supprimé le dossier .git, exécuter :
```
git rm --cached themes/ananke
```

2. `hugo.toml`

Vérifier que baseURL correspond à l'adresse finale du site dans Coolify (le sous-domaine donné par l'enseignant) :

hugo.toml
baseURL = 'https://portfolio-hugo-demo.app.ndlpavranches.fr/'
languageCode = 'fr-fr'
title = "Portfolio de Camille DURAND"
theme = 'ananke'

Explications :

Une baseURL incorrecte (par exemple celle de GitLab Pages) produit des liens vers un autre site, ou des pages sans mise en forme.
Il faut conserver le / final.
L'adresse exacte est communiquée par l'enseignant (voir la partie C, étape 3).

3. `Dockerfile`

Créer un fichier Dockerfile à la racine du projet (à côté de hugo.toml), avec ce contenu :

# Étape 1 : construire le site avec Hugo (version extended)
FROM hugomods/hugo:exts AS build
WORKDIR /src
COPY . .
RUN hugo --minify

# Étape 2 : servir les fichiers générés avec Nginx
FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /src/public /usr/share/nginx/html

Explications :

Le Dockerfile contient deux étapes (multi-stage build). Hugo n'est présent que dans la première : l'image finale ne contient que Nginx et les fichiers du site, ce qui la rend très légère.
hugomods/hugo:exts est une image Docker contenant la version extended de Hugo, comme celle installée sur votre poste.
hugo --minify construit le site dans /src/public en réduisant la taille des fichiers. Sans l'option -D, les pages en draft: true ne sont pas publiées : vérifier que chaque page à publier est bien en draft: false.
Le tag exts suit la dernière version de Hugo. Pour retrouver exactement la version de votre poste, lancer hugo version puis remplacer exts par exts-<version> (par exemple exts-0.140.0), après avoir vérifié que ce tag existe sur Docker Hub.

4. `nginx.conf`

Créer un fichier nginx.conf à la racine du projet, avec ce contenu :

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # Le HTTPS est géré par Traefik (Coolify) : ne pas générer de redirections absolues en http
    absolute_redirect off;

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
}

Explications :

Nginx écoute en HTTP sur le port 80 : le HTTPS est géré par Traefik, le proxy de Coolify.
try_files $uri $uri/ =404 sert le fichier demandé, ou le fichier index.html du dossier correspondant (Hugo génère apropos/index.html pour la page /apropos/).
absolute_redirect off évite que Nginx, qui ne voit que du HTTP, redirige /apropos vers http://... au lieu de https://....
error_page 404 /404.html affiche la page d'erreur 404.html générée par Hugo (si le thème en fournit une).

5. `compose.yaml`

Créer un fichier compose.yaml à la racine du projet, avec ce contenu :

services:
  web:
    build: .
    restart: unless-stopped

Explications :

build: . : l'image du service web est construite à partir du Dockerfile situé à la racine du projet.
Aucun ports: n'est publié : Coolify (via son proxy Traefik) route le trafic vers le port 80 du service web.
Aucune variable ${VARIABLE} : il n'y a rien à configurer dans l'onglet Environment Variables de Coolify.

6. `.dockerignore`

Créer un fichier nommé exactement .dockerignore à la racine du projet (à côté du Dockerfile), avec ce contenu :

.git/
.idea/
.vscode/
public/
resources/_gen/
.hugo_build.lock
node_modules/

Explications :

Ces fichiers ne sont pas copiés dans l'image par le COPY . . du Dockerfile : historique Git, réglages de l'éditeur, et résultats d'une construction locale (le dossier public/ est reconstruit par Hugo dans le conteneur).
Ne pas ajouter themes/ : le thème est nécessaire à la construction.

7. `.gitignore`

Vérifier que le fichier .gitignore (à créer s'il n'existe pas) contient :

public/
resources/_gen/
.hugo_build.lock

Explications :

Ces dossiers sont régénérés par Hugo : inutile de les envoyer sur GitHub.

B) Pousser les modifications sur GitHub

git status
git add .
git commit -m "Préparer le déploiement Coolify (Hugo, Nginx)"
git push origin main

Explications :

Coolify déploie ce qui est sur GitHub : tous les fichiers créés ou modifiés en A doivent être poussés sur la branche main.
git status permet de vérifier la liste des fichiers modifiés avant le git add. Vérifier en particulier que les fichiers du thème (dossier themes/ananke/) apparaissent bien comme nouveaux fichiers à ajouter.
Le dépôt doit être public, car la ressource Coolify est de type Public Repository.
Le fichier .gitlab-ci.yml éventuellement présent (publication sur GitLab Pages) n'a pas d'effet sur Coolify : il peut rester dans le projet.

MAJ du projet par l'étudiant

Après chaque modification du Portfolio, suivre ces étapes dans l'ordre.

5.1 Tester en local

hugo server -D

Ouvrir http://localhost:1313/ et vérifier que le site s'affiche comme prévu.

Puis vérifier que la construction finale (sans les brouillons) fonctionne :

hugo --minify

Aucune erreur ne doit s'afficher. Si une page est visible avec hugo server -D mais absente du site publié, elle est encore en draft: true.

5.2 Pousser les modifications sur GitHub

git status
git add .
git commit -m "Description de la modification"
git push origin main

Vérifier avec git status que seuls les fichiers attendus sont ajoutés.

Attendre la fin du git push avant de demander le déploiement dans Coolify : Coolify déploie le dernier commit présent sur GitHub, pas celui de votre poste. Pour vérifier que le push est bien terminé :

git status

Le message doit indiquer Your branch is up to date with 'origin/main'.

Puis prévenir l'enseignant, qui lance le déploiement (voir « MAJ du projet par l'enseignant »).

C) Créer la ressource dans Coolify

1. Créer la ressource

Projet → choisir l'environnement (ex. 2026-sio2-portfolio) → + New Resource.
Choisir Public Repository.
Saisir l'URL du dépôt dans l'unique champ Repository URL (https://) : https://github.com/votre-compte/mon-portfolio, puis valider (Check repository).
Sur l'écran suivant, renseigner la configuration de la ressource :
- Branch : main
- Build Pack : Docker Compose
- Base Directory : /
- Docker Compose Location : /compose.yaml
Cliquer sur Continue : la ressource est créée et ouverte sur sa page Configuration.

2. Variables d'environnement

Rien à renseigner : le compose.yaml d'un projet Hugo ne contient aucune variable ${VARIABLE}.

3. Définir le sous-domaine

Dans l'onglet General, le champ Domains apparaît pour le service du compose. Pour le service web, saisir par exemple :
```
https://portfolio-hugo-demo.app.ndlpavranches.fr
```
Cette adresse doit être identique à la baseURL du fichier hugo.toml de l'étudiant (partie A, étape 2). Nginx écoute sur le port 80 : il n'y a pas de port à ajouter.
Cliquer sur Save. Coolify génère le routage Traefik et le certificat Let's Encrypt.
Chez le gestionnaire DNS du domaine, créer un enregistrement de type A pour ce sous-domaine, pointant vers l'adresse IP du serveur Coolify.

D) Déployer

Cliquer sur Deploy (en haut de la ressource), puis suivre les logs du déploiement. Une fois terminé, le site est accessible à l'adresse du sous-domaine.

Dépannage : le site s'affiche sans mise en forme, ou les liens pointent vers un autre site

La baseURL du fichier hugo.toml ne correspond pas à l'adresse du site dans Coolify. Corriger baseURL dans le projet, pousser la modification sur GitHub, puis relancer Deploy.

Dépannage : le site affiche une page vide, ou le build échoue avec `module "ananke" not found`

Le thème n'est pas dans le dépôt GitHub (voir A, étape 1). Sur GitHub, ouvrir le dossier themes/ du dépôt : le dossier ananke doit contenir des fichiers. S'il apparaît comme un élément grisé ou vide :

Dans le projet, supprimer themes/ananke/.git.
Exécuter git rm --cached themes/ananke, puis git add ..
Faire un git commit et un git push origin main, puis relancer Deploy.

Dépannage : une page est introuvable (erreur 404)

Si la page existe en local avec hugo server -D mais pas en ligne, elle est encore en draft: true. La passer en draft: false, pousser sur GitHub, puis relancer Deploy.

MAJ du projet par l'enseignant

Après chaque modification du Portfolio poussée par l'étudiant, suivre ces étapes dans l'ordre.

5.3 Redéployer dans Coolify

Dans la ressource Coolify :

dans l'onglet General, cliquer sur le bouton Reload Compose file
cliquer sur le bouton Deploy (en haut à droite), puis suivre les logs du déploiement.
Coolify récupère le dernier commit de la branche main, reconstruit l'image (Hugo reconstruit le site, puis Nginx le sert) et redémarre le conteneur.
Le déploiement n'est pas lancé automatiquement par un git push : il faut cliquer sur Deploy.
Au début du log de déploiement, la ligne Importing votre-compte/mon-portfolio:main (commit sha …) indique le commit réellement déployé. Il doit correspondre au dernier commit poussé par l'étudiant (git log -1 --format=%H). Sinon, le déploiement a été lancé trop tôt : relancer Deploy.

5.4 Vérifier

Ouvrir le site à l'adresse du sous-domaine et tester la modification.
En cas d'erreur, consulter les logs du déploiement (une erreur Hugo y apparaît à l'étape RUN hugo --minify), puis les logs du conteneur web dans Coolify.

A) Adapter le projet Hugo​

1. Le thème doit faire partie du dépôt​

2. hugo.toml​

3. Dockerfile​

4. nginx.conf​

5. compose.yaml​

6. .dockerignore​

7. .gitignore​

B) Pousser les modifications sur GitHub​

MAJ du projet par l'étudiant​

5.1 Tester en local​

5.2 Pousser les modifications sur GitHub​

C) Créer la ressource dans Coolify​

1. Créer la ressource​

2. Variables d'environnement​

3. Définir le sous-domaine​

D) Déployer​

Dépannage : le site s'affiche sans mise en forme, ou les liens pointent vers un autre site​

Dépannage : le site affiche une page vide, ou le build échoue avec module "ananke" not found​

Dépannage : une page est introuvable (erreur 404)​

MAJ du projet par l'enseignant​

5.3 Redéployer dans Coolify​

5.4 Vérifier​

A) Adapter le projet Hugo

1. Le thème doit faire partie du dépôt

2. `hugo.toml`

3. `Dockerfile`

4. `nginx.conf`

5. `compose.yaml`

6. `.dockerignore`

7. `.gitignore`

B) Pousser les modifications sur GitHub

MAJ du projet par l'étudiant

5.1 Tester en local

5.2 Pousser les modifications sur GitHub

C) Créer la ressource dans Coolify

1. Créer la ressource

2. Variables d'environnement

3. Définir le sous-domaine

D) Déployer

Dépannage : le site s'affiche sans mise en forme, ou les liens pointent vers un autre site

Dépannage : le site affiche une page vide, ou le build échoue avec `module "ananke" not found`

Dépannage : une page est introuvable (erreur 404)

MAJ du projet par l'enseignant

5.3 Redéployer dans Coolify

5.4 Vérifier