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.

L'utilisation de ce service implique l'acceptation des pré-requis et recommandations mentionnés sur la page relatives à l'hébergement de pages web sur la PLM.

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 ".

Remarque importante pour le choix du nom du projet

Choisissez bien le nom du projet, puisqu'il déterminera l'adresse web du site. Si votre nom d'utilisateur est toto et que vous appelez le projet webpage, alors le site se trouvera en https://toto.pages.math.cnrs.fr/webpage. Cas particulier (recommandé) : si vous appelez votre projet précisément toto.pages.math.cnrs.fr, alors le site se trouvera en https://toto.pages.math.cnrs.fr, sans sous-répertoire. Vous trouverez plus de détails sur le nommage au paragraphe suivant.

Il ne vous reste plus qu'à mettre les fichiers de votre site web dans le répertoire public de votre projet.

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.

Si vous êtes à l'aise avec git, vous pouvez faire toutes les modifications sur votre ordinateur local, puis les envoyer sur le serveur.

Lorsqu'un nouveau commit est détecté, les pages sont 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 du sous-menu Deploy/Pages de votre projet, onglet Domains & Settings. Nous conseillons d'y désactiver l'option Use unique domain, pour que l'adresse du site soit prévisible.

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: busybox. 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.

Droits de consultation du site généré

Si votre projet est "privé", par défaut, le site n'est pas accessible à tout le monde. Il n'est visible que par les membres du projet. Si vous voulez rendre le site accessible à tout le monde, il faut modifier 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".

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 votre username comporte un "." (par exemple prenom.nom) alors il vous faut créer un groupe en remplaçant le "." par un "-" afin de permettre l'accès sécurisé (https://) à votre site (selon l'exemple précédent, le nom du groupe est prenom-nom).

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.

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.

La configuration d'un "Custom domains"

Cette configuration se fait dans le sous-menu "Pages" du menu "Deploy". Il faut cliquer sur "Nouveau domaine" et saisir le nom de domaine.

Attention ! "Use unique domain" ne doit pas être coché.

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 math-in-france.fr, il faut saisir les informations suivantes :

math-in-france.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".

Si votre domaine appartient à math.cnrs.fr, il faut demander à support@math.cnrs.fr de faire l'enregistrement DNS suivant. 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

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".