Vous trouverez dans cet article, l’ensemble des éléments permettant de mettre en place un site web static en se basant sur les outils suivants :

• Hugo : Générateur de site web static
• Github : Service web d’hébergement et de gestion des sources de développements (utilisant l’outil Git)
• Github Actions : Service Github permettant de tester et deployer les développements
• Gandi : Fournisseur du nom de domaine

Objectif

• Création d’un dépôt Github pour stocker les sources permettant de générer le site web static (documentation)
• Création d’un dépôt Github pour stocker les éléments du site web static (pragmatias.github.io)
• Configurer Github Actions pour déclencher la génération du site web static dans le dépôt pragmatias.github.io lors d’un commit dans la branche master du dépôt documentation
• Gestion du nom de domaine personnel chez Gandi pour afficher le site web static avec l’adresse pragmatias.fr

Code source

L’ensemble du code source de ce site se trouve sur mon dépôt github

Création des dépôts sur Github

Création du dépôt documentation

Pré-requis : avoir un compte sur Github

1. Sur la page listant vos dépôts, cliquez sur New

2. Renseignez le nom de votre dépôt qui contiendra les sources permettant de générer le site web et cliquez sur Create repository

3. Github vous affichera les étapes pour initialiser votre dépôt

Création du dépôt pragmatias.github.io

Il faut faire les mêmes étapes que pour la création du dépôt documentation mais cette fois avec le nom pragmatias.github.io.

Il faut créer au moins un fichier dans le dépôt pragmatias.github.io pour la suite de la configuration du dépôt.

Vous trouverez plus d’information sur le systeme Pages de Github sur le site officiel.

Si vous voulez modifier la configuration par défaut :

1. Allez dans la page Settings du dépôt pragmatias.github.io

2. Allez dans la section GitHub Pages pour configurer les informations nécessaires (custom domain, enforces HTTPS, …)

Configuration des actions sur les dépôts Github

Gestion d’un jeton personnel Github

Il faut commencer par créer un jeton Github permettant de donner le droit à Github Actions de faire la mise à jour du dépot cible.

1. Connectez vous sur votre compte Github, allez dans settings et cliquez sur Developer settings

2. Cliquez sur Personal access tokens, puis cliquez sur Generate new token

3. Remplissez le champ Tocken description, puis selectionnez les droits nécessaires (repo et gist) et cliquez sur Generate token

4. Copiez le code indiqué après la génération du jeton (il ne s’affichera qu’une seule fois)

5. Allez dans Settings du dépôt, sélectionnez l’option Actions dans le menu General > Security > Secrets

6. Cliquez sur le bouton New repository secret et renseignez le champ Name avec la valeur PERSONAL_TOKEN et le champ Value avec la valeur du jeton récupéré à l’étape n°4

Création du fichier de configuration pour Github Actions

Pour pouvoir déployer automatiquement le site web à partir du dépôt documentation vers le dépôt pragmatias.github.io, il faut créer un fichier main.yml dans le répertoire .github/workflows du dépôt documentation

 1# This is a basic workflow to help you get started with Actions
 2
 3name: main
 4
 5# Controls when the workflow will run
 6on:
 7  # Triggers the workflow on push or pull request events but only for the master branch
 8  push:
 9    branches: [ master ]
10  pull_request:
11    branches: [ master ]
12  
13  # Allows you to run this workflow manually from the Actions tab
14  workflow_dispatch:
15  
16# A workflow run is made up of one or more jobs that can run sequentially or in parallel
17jobs:
18  # This workflow contains a single job called "build"
19  build:
20    # The type of runner that the job will run on
21    runs-on: ubuntu-latest
22
23    # Steps represent a sequence of tasks that will be executed as part of the job
24    steps:
25      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
26      - uses: actions/checkout@v3
27      # Runs a single command using the runners shell
28      - name: Setup Hugo
29        uses: peaceiris/actions-hugo@v2
30        with:
31          hugo-version: 'latest'
32
33      - name: Cleaning
34        run: rm -rf public 2> /dev/null
35
36      - name: Build
37        run: hugo --minify
38
39      - name: AfterBuild
40        run: echo "www.pragmatias.fr" > public/CNAME
41 
42      - name: Deploy
43        uses: peaceiris/actions-gh-pages@v3
44        with:
45          personal_token: ${{ secrets.PERSONAL_TOKEN }}
46          external_repository: pragmatias/pragmatias.github.io
47          publish_branch: master  # default: gh-pages
48          publish_dir: ./public

Le contenu du fichier est le suivant :

• Utilisation de la distribution Ubuntu runs-on: ubuntu-latest
• Recuperation et installation de l’outil Hugo pour Linux name: Setup Hugo
• Suppression du répertoire public qui est le répertoire par défaut de génération de l’outil Hugo name: Cleaning
• Exécution de l’outil Hugo name: Build
• Pour la partie déploiement :
• On défini que l’on souhaite déployer le contenu du répertoire public dans la branche master du dépôt pragmatias/pragmatias.github.io

Utilisation d’un domaine personnel avec Github Pages

Note : J’utilise le nom de domaine pragmatias.fr chez Gandi

1. Dans les paramètres du dépôt pragmatias.github.io, renseignez la section Custom domain

pour forcer l’utilisation du https, sélectionnez l’option Enforce HTTPS

2. Configurez votre domaine pour rediriger les utilisateurs vers le contenu des Pages du dépôt pragmatias.github.io

2.1. Allez sur le site de Gandi, cliquez sur Nom de domaine, puis sur le nom de domaine souhaité

2.2. Allez dans Enregistrement DNS pour modifier les enregistrements

2.3. Ajouter les enregistrements DNS suivants (pour faire la redirection entre le service Pages de Github et votre nom de domaine)

1www 10800 IN CNAME pragmatias.github.io

Attention à ne pas avoir d’autres lignes commençant par @ 1800 IN A ou par www

La modification des enregistrements peut mettre plusieurs heures à se propager pour être prise en compte.