PLMlab Pages

Le service Pages est basé sur un dépôt git au sein d'un projet dans PLMlab. Les fichiers html doivent donc être intégrés au dépôt git.

Cette solution ne convient pas pour un site volumineux (>200Mo) qui contient de nombreux fichiers pdf, images ou vidéos car un dépôt git n'est pas adapté au stockage de ce type de fichier.

La première chose à faire est donc de se connecter sur PLMlab.

Lien vers la documentation officielle de Pages

Ce que permet Pages

• l'hébergement de pages HTML brutes,
• l'hébergement de pages HTML générées à l’aide d’un générateur de site statique (Hugo, Pelican, mkdocs, ...),
• l'accès à ces pages web depuis l'URL souhaitée grâce à la fonctionnalité "Custom domains" de gitlab (le certificat pourra être automatiquement géré par Let's Encrypt)

Ce que ne permet pas Pages

• la gestion des droits d'accès via un .htaccess,
• les statistiques générées à partir des fichiers de log du serveur web.

Création d'un projet pour l'hébergement de pages html

Vous pouvez créer un nouveau projet à partir d'un template et choisir le template "Pages/Plain HTML ". Il ne vous reste plus qu'à mettre les fichiers de votre site web dans le répertoire public.

Dans un premier temps, pour les utilisateurs qui ne connaissent pas encore git il est possible d'utiliser la fonctionnalité Web IDE proposée par PLMlab.

Une fois les modifications effectuées, il faut faire Commit afin de sauvegarder les modifications dans le dépôt. Attention de bien sélectionner "Commit to master branch" ou "Commit to main branch" et mettre un message de commit si vous le souhaitez.

Les pages vont être traitées par la fonctionnalité "CI/CD" de plmlab (vous pouvez voir l'avancée du traitement dans le menu CI/CD -> Pipelines de votre projet). Une fois le traitement terminé, vous pouvez accéder à vos pages via l'URL indiquée dans les réglages sous-menu Pages de votre projet.

Les opérations réalisées pendant la phase d'intégration continue "CI/CD" sont déclenchées à chaque commit et sont définies dans le fichier .gitlab-ci.yml.

• En particulier le nom de la branche du dépôt concerné est spécifié (master si vous avez utilisé le template et main si vous avez créé un nouveau projet).
• L'image du container Docker utilisée pour ce traitement est indiquée au début du fichier .gitlab-ci.yml. Dans le template c'est image: alpine:latest. Cette image est récupérée sur le site docker.io qui a mis en place des restrictions. Nous vous conseillons de ne pas spécifier d'image (en commentant ou en supprimant la ligne) afin que ce soit l'image par défaut du gitlab-runner qui soit utilisée. Vous pouvez aussi utiliser l'image alpine hébergé sur plmlab.

Création d'un projet pour l'hébergement de pages générées par un générateur de site statique

Comme pour l'hébergement de pages html, le plus simple est d'utiliser un template s'il existe pour le générateur de site que vous avez choisi. Vous pourrez aussi trouver des exemples ici.

Le principe :

• Vous ajoutez des fichiers au format de votre générateur de site web statique dans le dépôt git du projet que vous venez de créer
• Une tâche d’intégration continue va se lancer automatiquement après chaque "commit" afin de générer les pages web statiques (fichiers html et autres).
• Ces pages html vont être publiées par gitlab-pages sur l'URL (les URL) indiquées dans les réglages sous-menu Pages de votre projet.

Le nommage des URL

Par défaut les pages sont accessibles via une URL préfixée par https://quelquechose.pages.math.cnrs.fr. Tout est détaillé ici.

Par exemple, si mon username est toto et que je crée un projet toto.pages.math.cnrs.fr, il sera accessible à l'URL https://toto.pages.math.cnrs.fr.

Si je souhaite une URL de la forme https://quelquechose.pages.math.cnrs.fr, je peux créer un groupe appelé quelquechose et créer un projet quelquechose.pages.math.cnrs.fr dans ce groupe. C'est aussi de cette façon qu'il faudra faire s'il y a un "." dans le username.

La configuration d'un "Custom domains"

Cette configuration se fait dans le sous-menu "Pages" des réglages du projet. Il faut cliquer sur "Nouveau domaine" et saisir le nom de domaine.

Vous pouvez utiliser Let's Encrypt afin de générer automatiquement des certificats pour l'utilisation de https, ou vous pouvez choisir de désactiver cette fonctionnalité et saisir vos certificats pour ce nom de domaine. Si vous choisissez Let's Encrypt, il est nécessaire que l'accès à vos pages soit public (voir les explications au paragraphe).

PLMlab vous demande de faire un enregistrement DNS relatif au nom de domaine que vous avez indiqué.

Attention : Pour GANDI et pour d'autres fournisseurs de nom de domaine il faut légèrement adapter ces informations. Par exemple pour le domaine plmdoc.math.cnrs.fr, il faut saisir les informations suivantes :

plmdoc.math.cnrs.fr     IN A  147.210.130.49
                        TXT   gitlab-pages-verification-code=dd95dc0b8ccf02128ad7f074ca36888f

Le code de vérification hexadécimal (dd95dc0b8ccf02128ad7f074ca36888fdans notre exemple) doit être remplacé par celui indiqué par PLMlab. Une fois cet enregistrement DNS fait, il faudra attendre quelques heures afin que la propagation soit effective. Le "Verification status" passera alors à "Verified" soit automatiquement au bout d'un certain temps soit suite à votre action du clic sur "Retry verification".

Exemple : l'hébergement sur "mon_login.perso.math.cnrs.fr"

Dans "Domaine", il faut saisir mon_login.perso.math.cnrs.fr et laisser activé "Automatic certificate management using Let's Encrypt" puis cliquer sur "Créer le nouveau domaine".

Il faut alors demander à support@math.cnrs.fr de faire l'enregistrement DNS suivant

mon_login.perso.math.cnrs.fr    IN A  147.210.130.49
                                TXT   gitlab-pages-verification-code=d5c6bdb1fa441ef61cc13e225426bd18

mon_login doit être remplacé par votre login et gitlab-pages-verification-code=doit indiquer le code de vérification fourni par plmlab.

Une fois cet enregistrement DNS fait, il faudra attendre quelques heures afin que la propagation soit effective. Le "Verification status" passera alors à "Verified" soit automatiquement au bout d'un certain temps soit suite à votre action du clic sur "Retry verification".

Droits de consultation du site généré

Tout d'abord, il n'y a pas de lien entre les droits sur le repository gitlab et les droits de consultation des pages produites.

Vous pouvez fixer la visibilité de vos "pages". Allez dans "Settings"-"General", au paragraphe "Visibility, project features, permissions", allez au niveau de "Pages". Pour une consultation publique de vos pages, il faut choisir "everyone".

Utilisation de containers hébergés sur plmlab

Pour les tâches d'intégration continue il faut utiliser un container Docker. Une liste de containers hébergés sur plmlab et accessibles à tous les utilisateurs est disponible ici : https://docker-images.pages.math.cnrs.fr.