Réunion X/Stra 9 décembre 2022

---

Publier avec GitLab Pages

Diaporama - Page unique

---

Matthieu Boileau

IRMA, CNRS, Université de Strasbourg

---

CC BY 4.0

GitLab Pages

À partir de projets hébergés sur https://git.unistra.fr, GitLab Pages permet de :

• publier un site web statique, construit par exemple avec un générateur de site statique
• publier automatiquement de la documentation de code
• mettre en ligne des pdf (articles de livres, de cours, d'énoncés d'exercices, etc.) construits à partir de sources (Tex, markdown, etc.)
• mettre en ligne des diaporamas, comme celui-ci...

Du point de vue l'utilisateur

Permet de publier sur une URL en unistra.fr

Pages permet de publier sur une URL qui contient un nom de projet ou d'équipe.

Pour le projet GitLab projectname qui appartient à username ou groupname, l'adresse de publication sera :

https://[username|groupname].pages.unistra.fr/[projectname]

projectname est absent de l'URL s'il vaut [username|groupname].pages.unistra.fr

Permet de faire de l'édition collaborative

• Utiliser Git et GitLab pour enregistrer et fusionner les différentes contributions
• Utiliser GitLab Pages pour reconstruire le site ou le document en ligne après chaque modification sur le dépôt GitLab
• Contrairement à github (dans sa version gratuite), GitLab permet d'héberger les sources dans un dépôt privé.
• Le site Pages lui-même peut être public ou privé.

Très facile à mettre en oeuvre

En deux temps, trois mouvements :

1. On enregistre un gitlab runner ou on utilise un runner partagé
2. On ajoute un fichier .gitlab-ci.yml décrivant le job d'intégration continue

Limitations et solutions

• pas de contenu web dynamique : on ne peut pas exécuter de code côté serveur,
• une taille maximale de contenu publiable (100Mo par défaut) ; peut être étendu par l'admin.
• l'URL de publication contient forcément .pages.unistra.fr mais si l'admin l'active, on peut ajouter un nom de domaine personnalisé. Exemple local : https://imucentennial.math.unistra.fr

Du point de vue de l'administrateur

Avantages

• aucune intervention nécessaire de la part de l'admin : la publication est automatiquement déclenchée par le job d'intégration continue
• on évite de gérer à la main "un site web => un serveur web (ou un virtualhost)" : Pages le fait automatiquement !
• pas de problème de sécurité lié à du contenu dynamique : l'exécution de code (php ou autre) n'est pas autorisée.

Configuration

Quelques lignes dans le fichier /etc/gitlab/gitlab.rb :

################
# gitlab pages #
################
pages_external_url 'https://pages.unistra.fr'

pages_nginx['redirect_http_to_https'] = true
pages_nginx['ssl_certificate'] = "/etc/gitlab/ssl/star_pages_unistra_fr.pem"
pages_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/star_pages_unistra_fr.key"

• les 3 dernières lignes sont nécessaires pour avoir un site en https
• star_pages_unistra_fr.[pem|key] sont les fichiers du certificat wildcard qui est nécessaire pour publier sur *.pages.unistra.fr.

Suivi de l'utilisation de Pages

La version actuelle de GitLab ne fournit pas d'outil pour monitorer l'utilisation de Pages. Voici un script permettant de lister les contenus publiés avec Pages :

sudo gitlab-admin/gitlab_pages.py 
[sudo] password for xxx: 
Exploring default Pages path: /var/opt/gitlab/gitlab-rails/shared/pages/ 
tonus:
	https://tonus.pages.math.unistra.fr/schnaps/kirsch (9,5M)
	https://tonus.pages.math.unistra.fr/schnaps/schnaps (119M)
formation-python:
	https://formation-python.pages.math.unistra.fr (5,2M)
[...]
formation-info:
	https://formation-info.pages.math.unistra.fr/gitlab-pages (32K)
	https://formation-info.pages.math.unistra.fr/expose-git (1,3M)
	https://formation-info.pages.math.unistra.fr/atelier-gitlab --> WARNING: directory is empty
	https://formation-info.pages.math.unistra.fr/expose-git-example/methodus-inveniendi-addII.pdf (2,3M)
boileau:
	https://boileau.pages.math.unistra.fr/tp-gitlab (4,0M)
	https://boileau.pages.math.unistra.fr/website (68K)
	https://boileau.pages.math.unistra.fr/relax (4,1M)

Précautions

• il est très facile passer du contenu privé (projet gitlab) à du contenu public (Pages)
• privilégier la publication d'une branche identifiée (généralement master)
• s'assurer que les utilisateurs adhèrent à une charte

Démonstration

• Objectif : mettre en ligne la présentation actuelle
• Contrairement à la plupart des démos disponibles en ligne, on part de zéro.

Etape 1 : création d'un projet sur git.unistra.fr

• On réiniatilise le dépôt local actuel pour la démo

git checkout master  # on bascule sur la branche master
git branch -D dev    # on efface la branche dev
git rm .gitlab-ci.yml
git commit -m "Remove .gitlab-ci.yml to restart a new demo"
git remote remove demo  # on efface le remote demo
git push origin master

• Dans le dépôt local existant, on ajoute le remote demo :

export GROUPNAME=gitlab-pages  # Remplacez par le vôtre
git remote add demo git@git.unistra.fr:$GROUPNAME/demo.pages.unistra.fr.git

• On pousse le dépôt git actuel vers ce nouveau remote :

git push demo master

Cette action crée le nouveau projet gitlab-pages-demo

• On bascule sur une branche de dev :

git checkout -b dev

Etape 2 : identification d'un gitlab runner

• GitLab Pages repose sur le workflow d'intégration continue de GitLab : gitlab-ci
• Avec gitlab-ci, les jobs d'intégration continue sont assurés par les gitlab runners
• Pour utiliser un runner spécifique, cf. Annexe
• L'instance git.unistra.fr propose des runners partagés
• On explore les runners disponibles sur la page du projet dans la page dédiée aux runners :

CI / CD > Runners settings

• On choisit le runner partagé identifié par le tag cluster.

Etape 3 : configuration du fichier gitlab-ci.yml

Avec GitLab-CI, toute l'intégration continue est décrite par un fichier unique .gitlab-ci.yml qui doit être présent dans la racine du projet :

cat > .gitlab-ci.yml <<- EOM
image: boileaum/jupyter

pages:
  script:
    - pip install -r requirements.txt
    - jupyter nbconvert --to slides gitlab-pages.ipynb --output-dir=public
    - jupyter nbconvert --to html gitlab-pages.ipynb --output-dir=public
    - mv public/gitlab-pages.slides.html public/index.html
    - cp -r images public/
  tags:
    - cluster
  only:
    - master
  artifacts:
    paths:
      - public
EOM

avec :

• image: boileaum/jupyter l'image boileaum/jupyter du conteneur Docker chargé d'exécuter le script d'intégration continue
• pages: le job gitlab-ci doit obligatoirement porter ce nom
• jupyter nbconvert des commandes pour convertir ce notebook Jupyter en page html ou en diaporama Reveal.js
• public/ le répertoire dont le contenu sera publié par Pages

only:
    - master

Ce job ne sera exécuté que pour la branche master.

tags:
    - cluster

Avec le tag cluster, on cible le runner partagé.

artifacts:
    paths:
      - public

Nécessaire pour que le répertoire soit effectivement publié.

• On enregistre dans git

git add .gitlab-ci.yml gitlab-pages.ipynb
git commit -m "Add .gitlab-ci.yml to trigger GitLab Pages"

Etape 4 : on pousse vers le remote

git push -u demo

Cette action ne déclenche pas la chaîne d'intégration continue car cette dernière ne concerne que la branche master.

• On ouvre le lien affiché dans le retour console pour ouvrir une merge request sur GitLab
• On fusionne
• On surveille l'exécution du job d'intégration continue dans GitLab :

CI/CD > Pipelines

• Une fois le job CI terminé, on va dans la rubrique Pages du projet pour récupérer l'URL de publication :

Settings > Pages

Elle vaut ici https://demo.pages.unistra.fr

Publication vers une adresse courte

• En nommant le projet demo.pages.unistra.fr, c'est-à-dire <namespace>.pages.unistra.fr, on a publié sur https://demo.pages.unistra.fr
• Si le projet s'appelait simplement gitlab-pages, on aurait publié sur https://demo.pages.unistra.fr/gitlab-pages/

Conclusion

• GitLab Pages facilite la publication de contenu : sites web, pages perso, documentation de code, articles, support de cours, d'exposés, etc., le tout sur une URL institutionnelle.
• Pages fait partie intégrante de la chaîne d'intégration continue de GitLab
• gitlab-ci permet de gérer la construction du contenu html à partir de sources et de bénéficier du workflow GitLab (issues, MR, etc.)
• Combiner à un générateur de site statique, GitLab Pages peut être une façon de collaborer sur un site en se passant d'un CMS. Associé au système des merge requests et des reviews de code, on dispose d'une chaîne rédactionnelle : des rédacteurs soumettent, un chef de la rédaction valide.

Ressources

• Documentation officielle très complète
• De nombreux exemples pour démarrer
• Un tutoriel vidéo qui présente l'essentiel en 3min40.

Annexe : enregistrement d'un gitlab runner

GitLab Pages repose sur le workflow d'intégration continue de GitLab : gitlab-ci. Avec gitlab-ci, les jobs d'intégration continue sont assurés par les gitlab runners.

Pour plus de souplesse, on enregistre un gitlab runner de type Docker en suivant la doc officielle.

• On récupère le token d'intégration continue du projet sur la page du projet dans

Settings > CI / CD > Runners settings

• On positionne la variable d'environnement correspondante

#export REGISTRATION_TOKEN=my-registration-token

• On enregistre le runner

gitlab-runner register --non-interactive \
                       --name gl_runnner_for_$USER \
                       --url "https://git.unistra.fr" \
                       --executor docker \
                       --docker-image boileaum/jupyter \
                       --tag-list docker

• --docker-image boileaum/jupyter : le conteneur Docker chargé d'exécuter le script d'intégration continue sera basé sur l'image boileaum/jupyter
• --tag-list docker : pour solliciter ce runner, il faudra donc que le job CI porte le tag docker

On vérifie que le runner est actif

gitlab-runner list