Réunion X/Stra 9 décembre 2022
Publier avec GitLab Pages
Matthieu Boileau
IRMA, CNRS, Université de Strasbourg
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]
projectnameest 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 :
- On enregistre un
gitlab runnerou on utilise un runner partagé - On ajoute un fichier
.gitlab-ci.ymldé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.frmais 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
In [ ]:
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:
In [ ]:
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 :
In [ ]:
git push demo master
Cette action crée le nouveau projet gitlab-pages-demo
- On bascule sur une branche de dev :
In [ ]:
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.frpropose 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 :
In [ ]:
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/jupyterl'imageboileaum/jupyterdu conteneur Docker chargé d'exécuter le script d'intégration continuepages:le job gitlab-ci doit obligatoirement porter ce nomjupyter nbconvertdes commandes pour convertir ce notebook Jupyter en page html ou en diaporama Reveal.jspublic/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
In [ ]:
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¶
In [ ]:
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
In [ ]:
#export REGISTRATION_TOKEN=my-registration-token
- On enregistre le runner
In [ ]:
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'imageboileaum/jupyter--tag-list docker: pour solliciter ce runner, il faudra donc que le job CI porte le tagdocker
On vérifie que le runner est actif
In [ ]:
gitlab-runner list
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