Déploiement de Pelican sur Pages de PLMlab

Services numériques de la PLM Hébergement web
1

Bonjour tout le monde,

Après deux projets d’hébergement de site purement statique HTML sur PLMlab (un GDR et un site de fédé), je vais me lancer dans l’hébergement d’un site généré avec Pelican. Le HTML5 c’est sympa, mais bon, c’est lourd à écrire et maintenir…

J’ai vu Pelican mentionné de temps en temps sur les documentations, mais je n’ai pas mis la main sur un cas pratique. Mon objectif est de mettre en place quelque chose de similaire à l’exemple “officiel” sur GitLab.

Mon plan d’attaque est le suivant : Commencer par héberger les sources et générer le contenu de public “à la main” entre chaque commit, puis dans un second temps automatiser la génération “à chaque commit” via les outils de CI/CD de GitLab (comme dans la réf ci-dessus).

Avant même de commencer, une question basique : Quelqu’un a-t-il déjà mis ça en place ? Si oui, un retour à faire sur cette solution ?

Une seconde question, plutôt en direction de l’équipe PLM ou des usagers connaisseurs :
Concernant l’image utilisée par l’outil d’intégration GitLab, une image en particulier à conseiller ?
En consultant le répertoire d’images de la PLM je vois que l’image “Python” ne semble pas fonctionnelle. J’imagine que je dois pouvoir bricoler un apk add python3 sur l’image alpine, mais il y a certainement plus simple…

Je pourrai retranscrire mon expérience et documenter les petits détails techniques pour contribuer à la documentation si ça intéresse, une fois que ça fonctionnera.

2

Je pense avoir résolu tous les soucis pour un site “très simple”.
J’espère que ce qui suit servira/aidera/inspirera d’autres.

Organisation des fichiers

Sortie

Il est nécessaire d’indiquer dans pelicanconf.py l’export des fichiers dans le répertoire attendu par Pages:

OUTPUT_PATH = 'public/'

Plugins

J’ai personnellement utilisé un mix de répertoires locaux et de paquets Python.
Les gros plugins Pelican sont packagés dans Pypi et sont faciles à installer avec pip (cf. exemple plus loin le fichier .gitlab-ci.yml). Ici, j’ai activé render_math – installé par pip – mais j’ai une version personnelle de events sous suivi de version dans le répertoire pelican-plugins/events (j’ai modifié le plugin).
On peut certainement exploiter les submodules de Git, mais je n’ai pas étudié leurs interactions avec la chaîne CI/CD de GitLab.

PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['events', 'render_math']

Thème

Ayant eu à l’adapter, j’ai choisi de déployer une copie locale du thème nest dans le répertoire (sous Git) themes:

THEME = "themes/nest"

Configuration Pelican

Rien de particulier…

  • Penser à ne définir l’adresse du site que dans le fichier publishconf.py pour pouvoir tester en local.
    SITEURL = 'https://xyz.pages.math.cnrs.fr/1234'
  • J’ai un peu galéré avec les traductions automatiques des thèmes, probablement très dépendant des thèmes. Pour obtenir des dates au format français sans se soucier de l’image Docker de construction et ses paramètres, j’ai défini les deux variables suivantes dans pelicanconf.py. Les passer en ligne de commande à Python ne suffisait pas:
    TIMEZONE = 'Europe/Paris'
LOCALE = 'fr_FR.utf8'

Configuration CI/CD pour PLMlab

J’ai eu pas mal de soucis, et je remercie les personnes sur le Mattermost PLM pour leur aide.

Image à utiliser

L’image Python n’est pas utilisable actuellement. Après plusieurs essais, j’ai choisi d’installer Python dans la dernière Alpine.
Il est nécessaire d’être explicite sur l’image du conteneur PLM:

image: registry.plmlab.math.cnrs.fr/docker-images/alpine/edge:base

Les tags (ici base) utilisables sont listés dans chacune des images (ici alpine/edge) produites dans la section Container Registry du dépôt docker-images de la PLM…
Exemple pour Alpine Edge : lien direct

Déployer Python

Il va falloir installer Python et les dépendances, les lignes de scripts “qui font tout” :

script:
 - export PYTHONUNBUFFERED=1
 - apk add --update --no-cache python3
 - ln -sf python3 /usr/bin/python
 - python3 -m ensurepip
 - pip3 install --no-cache --upgrade pip setuptools
 - pip3 install -r requirements.txt

La variable exportée permet de pouvoir avoir un listing complet des commandes Python dans la console de suivi des pipeline GitLab, le reste est plutôt évident.
Je suppose ici que la racine de votre dépôt contient un fichier requirements.txt. Le mien pour l’exemple:

beautifulsoup4
Jinja2
Markdown
pelican
typogrify
pelican-render-math
icalendar

pelican-render-math permet d’installer ce plugin directement par pip, icalendar est une dépendance de events. On peut réduire le fichier à juste pelican et Markdown pour un site sans plugin.

Reconstruction du site à chaque commit

Je ne maitrise clairement pas les outils CI/CD de GitLab, j’ai dû décrire l’installation et la compilation du site dans la même tâche. Mais ça fonctionne ! Voilà le fichier .gitlab-ci.yml final:

image: registry.plmlab.math.cnrs.fr/docker-images/alpine/edge:base

site:
  stage: build
  script:
  - export PYTHONUNBUFFERED=1
  - apk add --update --no-cache python3
  - ln -sf python3 /usr/bin/python
  - python3 -m ensurepip
  - pip3 install --no-cache --upgrade pip setuptools
  - pip3 install -r requirements.txt
  - pelican content -s publishconf.py 
  artifacts:
    paths:
    - public

pages:
  stage: deploy
  needs: [site]
  script:
  - echo 'Nothing to do...'
  artifacts:
    paths:
    - public
  only:
  - master

Références

Je reste évidemment disponible (ici ou sur le Mattermost) si certains points ne sont pas assez clairs.

3

Petite mise à jour :

Après des soucis mineurs – mais réguliers et agaçants – avec Alpine, je suis passé sur l’image ubuntu/22.04:python3, le fichier .gitlab-ci.yml ressemble maintenant à ça :

image: registry.plmlab.math.cnrs.fr/docker-images/ubuntu/22.04:python3

site:
  stage: build
  script:
  - export PYTHONUNBUFFERED=1
  - apt update
  - apt --yes install python3-venv
  - python3 -m venv env
  - source env/bin/activate
  - pip3 install -r requirements.txt
  - LC_ALL=fr_FR.UTF-8 pelican content -s publishconf.py 
  artifacts:
    paths:
    - public

pages:
  stage: deploy
  needs: [site]
  script:
  - echo 'Nothing to do...'
  artifacts:
    paths:
    - public
  only:
  - master

J’aurais pu utiliser n’importe quelle autre distribution, mais vu que je développe là-dessus…