Git on Zwindler's Reflection

Une issue ouverte sur un projet, 7 ans après ?

Fri, 24 Nov 2023 14:00:00 +0200

Introduction

Il y a 7 ans, en août 2016 (!!), je créais ma première “vraie” image docker.

Il s’agissait d’une image custom pour un outil que j’utilisais énormément XWiki, un outil de Knowledge management open source (et français) que j’apprécie particulièrement et qui remplace avantageusement un Confluence (si vous voulez mon avis).

A l’époque, mon image fournissait un XWiki prêt à l’emploi avec Tomcat 8 et le driver JDBC pour postgresql.

github.com/zwindler/docker-xwiki

J’avais fait ce projet car les images officielles du projet étaient encore balbutiantes (ça date !) et ne proposaient pas cette alternative.

J’avais d’ailleurs écrit un article pour l’occasion (Installer XWiki 8.2.1 avec Docker (compose) en 2 lignes de commandes) et fourni au fil des mois suivants des manifests pour Kubernetes.

Et aujourd’hui ?

Ca fait bien longtemps que ce projet n’a plus aucun intérêt, même si mes images ont été téléchargées environ 30000 fois (quand même !), avec un dernier téléchargement l’an dernier, malgré une version vielle de plus de 6 ans (mais pourquoiiiiii ?).

hub.docker.com - zwindler/xwiki-tomcat8

Les images officielles proposent désormais (depuis bien longtemps) toutes les options les plus courantes pour toutes les versions supportées

Pourtant ?!?

Pourtant, début novembre, j’ai reçu une issue, d’un utilisateur qui m’informait qu’il ne pouvait pas rebuild mon image car l’URL permettant de télécharger les artefacts WAR ne répondait plus (effectivement, elle a changé).

Même si au début j’étais un peu interloqué, je me suis dis que ça pouvait être fun de remettre les mains dedans et de tenter de mettre à jour mon image sur toute la stack, pour voir si ça fonctionne encore.

Voyons voir ce qui a changé depuis 2016…

Évidemment, beaucoup de choses !

D’abord, les versions de XWiki (de 10 à 14), qui ont forcément évoluées, ainsi que cette fameuse URL de téléchargement des artefacts qui avait changé.

La version de postgres est passée de 9.5 à 16, les versions du driver JDBC ont évoluées de plusieurs mineures.

Plus impactant, tomcat est passé de la version 8 à la version 10, avec un gros breaking change entre la 9 et la 10, notamment à cause de JEE, renommé en JakartaEE !

Ca parlera aux Javaistes ;-)

Plus anecdotique, le MAINTAINER a disparu depuis bien longtemps des Dockerfile (remplacé par un LABEL opencontainers), le MaxPermSize n’existe plus en Java et le format des fichiers docker-compose est passé en version 3.

Les modifs

Pour le fun, j’ai donc réparé mon image pour qu’elle marche (et pas plus), puis j’ai passé le repo en readonly, pour la postérité, en prenant soin d’informer l’auteur de l’issue qu’il valait mieux regarder du côté des images officielles ;-).

Le code de fix est disponible ici, pour les curieux/curieuses.

Mais… ça fonctionne :-p

Automatiser son site Hugo sans Github Action ou Vercel

Tue, 01 Aug 2023 06:00:00 +0200

Contexte

Fin 2021, après plus de 10 ans à écrire des articles de blog tech sur Wordpress, je prenais la décision radicale d’arrêter de maintenir cette bouse infâme (je mâche mes mots) et de partir sur des articles rédigés en markdown et un site statique avec Hugo.

Au tout début, je gérais le blog moi-même mais assez vite j’en ai eu assez de devoir aller rebuild le blog à chaque modification. J’ai rapidement mis un cron qui faisait des git pull régulièrement, mais on ne va pas se mentir, c’est assez crado…

Finalement, on m’a rapidement pointé que je devrais arrêter de m’embêter et utiliser Netlify ou Vercel.

J’étais pas super chaud, car ça allait à l’encontre de ma volonté d’auto héberger mon contenu et de limiter l’impact sur la vie privée de mes lecteurs, mais finalement, l’expérience utilisateur sur Vercel était tellement bonne que j’avais craqué. Je ferai peut-être un article là-dessus d’ailleurs, c’est la première fois que j’ai compris (ressenti) l’intérêt d’un PaaS.

Mais aujourd’hui, je reviens sur cette décision et j’essaye de voir ce qu’il est nécessaire de mettre en place pour disposer soi-même d’un site hugo qui se refresh tout seul dès qu’un commit arrive sur le dépôt git, sans utiliser de plateforme type Vercel ni d’outils types Github action+pages.

Prérequis

Je pars du principe que vous avez déjà un site statique généré avec Hugo. Si ce n’est pas le cas je vous invite à aller lire mes articles précédents sur le sujet (premiers pas, stats avec matomo, migration wordpress vers hugo).

Vous avez donc un serveur Linux sur lequel vous avez la main pour installer des choses et un dépôt git (sous Github dans mon cas, mais on peut probablement adapter l’article pour autre chose).

Hugo étant d’abord un générateur de site statique, je vais utiliser nginx en frontal pour servir les fichiers qu’on va générer. Jusqu’à il y a peu, l’usage du mode “server” de hugo n’était d’ailleurs pas conseillé en production (mais ça ne semble plus être le cas, je n’ai pas vu de warning dernièrement ?).

apt install nginx git

Déposer les sources sur le serveur

Dans mon cas, les sources de mon blog ne sont pas disponibles publiquement (parce que j’ai pas envie, c’est comme ça ¯\_(ツ)_/¯).

Il faut donc préalablement se loguer en SSH avec git avant de pouvoir pull le code. Et comme je n’ai pas envie de laisser ma clé privée sur le serveur qui va héberger mon blog, il faut que j’utilise une autre clé.

Dans mon cas, Github, qui héberge le code markdown de mon blog, a une notion de “deploy keys”, qui servent justement pour ça :

docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys

Je vais donc créer une clé sur le serveur qui héberge le blog :

ssh-keygen -t ed25519 -C "xxx@xxx.tld"
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/toto/.ssh/id_ed25519):
[...]

Et je la copie dans le dossier de www-data (l’utilisateur nginx sous Ubuntu)

chmod 600 /root/.ssh/id_ed25519
sudo mkdir /var/www/.ssh/
sudo cp ~/.ssh/id_ed25519* /var/www/.ssh/
chown www-data: /var/www/.ssh/*

Une fois la clé créée, on doit l’ajouter dans Github.com. Je ne lui donne que les droits “read only” puisque le but c’est seulement de récupérer le code et générer le site statique, pas qu’on puisse éditer le code (cé pour la sécuritay).

Je retourne ensuite sur mon serveur et j’essaye de télécharger les sources et le thème:

cd /usr/share/nginx/html
GIT_SSH_COMMAND='ssh -i /var/www/.ssh/id_ed25519 -o IdentitiesOnly=yes' git clone git@github.com:zwindler/blog.example.org.git
cd blog.example.org/themes
git submodule add -f https://github.com/CaiJimmy/hugo-theme-stack.git
chown -R www-data: /usr/share/nginx/html/blog.example.org

Webhook

Pour réagir à l’arrivée d’un nouveau commit sur notre dépôt source, on va utiliser 2 choses :

un projet qui s’appelle sobrement “Webhook”.
configurer un webhook dans github, qui va envoyer l’info que quelque chose est arrivé sur le dépôt (mais on verra ça plus tard)

Revenons à “Webhook” dans un premier temps :

webhook is a lightweight configurable tool written in Go, that allows you to easily create HTTP endpoints (hooks) on your server, which you can use to execute configured commands. You can also pass data from the HTTP request (such as headers, payload or query variables) to your commands. webhook also allows you to specify rules which have to be satisfied in order for the hook to be triggered.

On récupère la dernière release et déposer le binaire sur notre serveur :

github.com/adnanh/webhook/releases/tag/2.8.1

export VERSION="2.8.1"
wget https://github.com/adnanh/webhook/releases/download/${VERSION}/webhook-linux-amd64.tar.gz

tar -xvf webhook*.tar.gz

sudo mv webhook-linux-amd64/webhook /usr/local/bin
rm -rf webhook-linux-amd64*

webhook --version

Une fois que c’est fait, on va générer une chaîne aléatoire qui va nous servir de “secret” qui sera partagé entre le binaire webhook qui tourne sur notre serveur et un webhook sur Github.com :

WHSECRET=`uuidgen | base64`
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa==

On crée un fichier de configuration hook.json pour déclarer nos webhooks

mkdir /etc/webhook
cat > /etc/webhook/hook.json << EOF
[
 {
 "id": "redeploy",
 "execute-command": "/usr/share/nginx/html/blog.example.org/blog_refresh.sh",
 "command-working-directory": "/usr/share/nginx/html/blog.example.org",
 "trigger-rule":
 {
 "match":
 {
 "type": "payload-hmac-sha1",
 "secret": "$WHSECRET",
 "parameter":
 {
 "source": "header",
 "name": "X-Hub-Signature"
 }
 }
 }
 }
]
EOF

Ici, quand le serveur va recevoir l’url /hooks/redeploy, on va lancer le script /usr/share/nginx/html/blog.example.org/blog_refresh.sh depuis le répertoire /usr/share/nginx/html/blog.example.org.

Charge à nous de créer un script qui va soit :

récupérer les sources (git pull)
relancer un build

Voilà à quoi pourrait ressembler le script blog_refresh.sh :

#!/bin/bash
cd /usr/share/nginx/html/blog.example.org

#pull latest version
GIT_SSH_COMMAND='ssh -i /var/www/.ssh/id_ed25519 -o IdentitiesOnly=yes' git clone git@github.com:zwindler/blog.example.org.git

#refresh theme submodule
git submodule init
git submodule update

#rebuild (fire and forget)
hugo --minify --gc &

On va ensuite créer un service systemd qui va lancer le binaire webhook en tâche de fond

cat > /etc/systemd/system/webhook.service << EOF
[Unit]
Description=Simple Golang webhook server
ConditionPathExists=/usr/local/bin/webhook
After=network.target

[Service]
User=www-data
Group=www-data
Type=simple
WorkingDirectory=/usr/share/nginx/html/blog.example.org
ExecStart=/usr/local/bin/webhook -ip 127.0.0.1 -hooks /etc/webhook/hook.json -verbose
Restart=on-failure

[Install]
WantedBy=default.target
EOF

systemctl enable webhook
systemctl start webhook

Côté Github.com, on crée le webhook qui va contacter le serveur webhook de la façon suivante :

On a maintenant un serveur web qui est en attente de certains événements webhooks et qui va lancer un script si jamais l’URL de webhook est appelée par Github.com.

Configuration nginx

Il reste maintenant toute la configuration de notre nginx en frontal à faire. En partant du principe qu’on vient juste de faire l’installation du package, on commence par supprimer le fichier /etc/nginx/sites-enabled/default, et on en crée un nouveau :

rm /etc/nginx/sites-enabled/default

cat > /etc/nginx/sites-available/blog.example.org.conf << EOF
# Root configuration
server {
 listen 80;
 server_name blog.example.org;

 location /hooks/ {
 proxy_pass http://127.0.0.1:9000/hooks/;
 }

 error_page 404 /404.html;

 location / {
 root /usr/share/nginx/html/blog.example.org/public;
 index index.html;
 }
}
EOF
ln -s /etc/nginx/sites-{available,enabled}/blog.example.org.conf

On vérifie que la configuration est valide et si oui on redémarre nginx

nginx -t
systemctl reload nginx

A partir de maintenant, toutes les URLs qui arriveront jusqu’à votre serveur en /hooks seront redirigées sur le logiciel “webhook” et le reste ira sur votre site statique (/usr/share/nginx/html/blog.example.org/public).

curl https://blog.example.org/hooks/redeploy -L
Hook rules were not satisfied.%

Ici le hook renvoie une erreur, car on a pas envoyé le token secret mais c’est probable que ça fonctionne. Toutes les autres pages renvoient bien une page du blog :

curl https://blog.example.org/
<!DOCTYPE html>
<html lang="fr-fr" dir="ltr">
 <head>
 <meta name="generator" content="Hugo 0.115.1"><meta charset='utf-8'>
[...]

On peut maintenant envoyer des commits et voir si ça déclenche des rebuilds de notre blog. Ou alors, on peut récupérer un push précédent et cliquer sur “Redeliver” si on veut trigger un rebuild du blog.

root@hugo:~# systemctl status webhook
* webhook.service - Simple Golang webhook server
 Loaded: loaded (/etc/systemd/system/webhook.service; enabled; vendor preset: enabled)
 Active: active (running) since Mon 2023-07-31 07:34:35 UTC; 33s ago
 Main PID: 900109 (webhook)
 Tasks: 15 (limit: 4574)
 Memory: 240.4M
 CPU: 45.504s
 CGroup: /system.slice/webhook.service
 |-900109 /usr/local/bin/webhook -ip 127.0.0.1 -hooks /etc/webhook/hook.json -verbose
 `-900161 hugo --minify --gc

Jul 31 07:34:35 hugo webhook[900109]: [webhook] 2023/07/31 07:34:35 attempting to load hooks from /etc/webhook/hook.json
Jul 31 07:34:35 hugo webhook[900109]: [webhook] 2023/07/31 07:34:35 found 1 hook(s) in file
Jul 31 07:34:35 hugo webhook[900109]: [webhook] 2023/07/31 07:34:35 loaded: redeploy
Jul 31 07:34:35 hugo webhook[900109]: [webhook] 2023/07/31 07:34:35 serving hooks on http://127.0.0.1:9000/hooks/{id}
Jul 31 07:34:35 hugo webhook[900109]: [webhook] 2023/07/31 07:34:35 os signal watcher ready
Jul 31 07:34:41 hugo webhook[900109]: [webhook] 2023/07/31 07:34:41 [f089a0] incoming HTTP POST request from 127.0.0.1:43258
Jul 31 07:34:41 hugo webhook[900109]: [webhook] 2023/07/31 07:34:41 [f089a0] redeploy got matched
Jul 31 07:34:41 hugo webhook[900109]: [webhook] 2023/07/31 07:34:41 [f089a0] redeploy hook triggered successfully
Jul 31 07:34:41 hugo webhook[900109]: [webhook] 2023/07/31 07:34:41 [f089a0] 200 | 0 B | 1.151688ms | 127.0.0.1:9000 | POST /hooks/redeploy
Jul 31 07:34:41 hugo webhook[900109]: [webhook] 2023/07/31 07:34:41 [f089a0] executing /usr/share/nginx/html/blog.example.org/blog_refresh.sh
[...]
Jul 31 07:37:28 hugo webhook[900109]: Pages | 3572
Jul 31 07:37:28 hugo webhook[900109]: Paginator pages | 516
Jul 31 07:37:28 hugo webhook[900109]: Non-page files | 14
Jul 31 07:37:28 hugo webhook[900109]: Static files | 2282
Jul 31 07:37:28 hugo webhook[900109]: Processed images | 2
Jul 31 07:37:28 hugo webhook[900109]: Aliases | 1563
Jul 31 07:37:28 hugo webhook[900109]: Sitemaps | 1
Jul 31 07:37:28 hugo webhook[900109]: Cleaned | 0
Jul 31 07:37:28 hugo webhook[900109]: Total in 166131 ms
Jul 31 07:37:28 hugo webhook[900109]: [webhook] 2023/07/31 07:37:28 [f089a0] finished handling redeploy

Conclusion

Si vous êtes à l’aise avec Linux et nginx, ces quelques manipulations sont assez rapides à faire, il n’y a rien de vraiment complexe.

Cependant, ça demande à l’usage un peu d’administration et de vouloir mettre les mains dans le cambouis (avoir une VM à gérer). Je ne peux reprocher à personne de préférer l’utilisation de Github/Gitlab pages, couplé à de Github actions/Gitlab runners, voire de tout déléguer à Vercel/Netlify…

Mais j’avais envie de reprendre la main sur le hosting de mon blog (avec tous les inconvénients que ça va avoir en termes de maintien en condition opérationnelle), notamment pour disposer à nouveau de l’IPv6 (perdue lors du passage à Vercel) et une navigation sur mon blog plus respectueuse de votre vie privée (pas que j’aie pas confiance en Vercel, mais bon…).

Et c’est en revanche beaucoup plus simple que d’héberger son propre serveur Gitlab + Gitlab runners + Gitlab pages ;-).

Donc, pour mon usage, ça fait le taf :)

Ressources additionnelles

J'ai enfin migré de Wordpress vers Hugo - partie 2

Mon, 29 Nov 2021 08:00:00 +0000

Cette article fait partie d’une suite d’articles :

Extraire les données de WordPress

Normalement si vous avez lu la première partie, vous savez qu’on a un Hugo fonctionnel (mais vide). Et que dans mon cas, l’objectif était de migrer 12 ans d’historique (350 articles tout de même) de Wordpress vers notre Hugo.

Vous vous en doutez, le but n’est pas de reprendre les articles uns par uns (sauf si vous n’en avez qu’une dizaine, ça doit se faire) mais bien de trouver une méthode pour exporter le contenu existant en markdown pour repartir comme si de rien n’était.

La documentation officielle de Hugo donne plusieurs pistes pour migrer depuis Wordpress et c’est la première que j’avais utilisé en 2019 (la première fois que j’avais tenté de migrer, sans succès). J’ai re-installé l’extension wordpress-to-hugo-exporter (je vous invite quand même à regarder les alternatives car il n’est pas impossible que ça ait évolué depuis).

wordpress-to-hugo-exporter

La première chose à faire pour installer cette extension est de vérifier que votre serveur qui héberge le WordPress dispose bien de l’extension PHP zip.so.

cat /etc/php.d/40-zip.ini
; Enable ZIP extension module
extension=zip.so

On peut ensuite cloner le projet git du plugin directement dans le dossier plugin de WordPress

cd PATH_TO_WORDPRESS/wp-content/plugins/
git clone https://github.com/SchumacherFM/wordpress-to-hugo-exporter

A partir de là, il est possible de démarrer un export soit depuis l’interface, soit via un script en PHP lancé depuis le serveur en ligne de commandes. Évidemment, dans ce genre de procédures, on arrive toujours à un moment où on se tape un timeout quelque part. Dans mon cas, les données exportées (articles + medias, environ ~1.5 Go) prenaient 500 Mo de RAM et 20 minutes d’exécution.

On oublie donc le clic dans l’interface (sauf à tuner votre nginx pour autoriser des requêtes clients avec un timeout > 60s) et on lance depuis la ligne de commande. Et bien entendu, on augmente toutes les limites possibles et imaginables, notamment celle de wordpress via le fichier wp-config.php.

// Set initial default constants including WP_MEMORY_LIMIT, WP_MAX_MEMORY_LIMIT, WP_DEBUG, SCRIPT_DEBUG, WP_CONTENT_DIR and WP_CACHE.
wp_initial_constants();
define( 'WP_MEMORY_LIMIT', '2048M' );
define( 'WP_MAX_MEMORY_LIMIT', '2048M' );

cd PATH_TO_WORDPRESS/wp-content/plugins/wordpress-to-hugo-exporter/
php hugo-export-cli.php memory_limit=-1

Qui devrait se terminer, si tout se passe bien, par un :

This is your file!
/tmp/wp-hugo.zip

Note: on peut également exporter les commentaires, il faut modifier manuellement une ligne dans le fichier hugo-export.php (voir la doc)

A partir de là, on a une archive qui contient vos posts, vos pages et vos médias importés (grosso modo tout wp-content).

L’archive a l’arborescence suivante :

un dossier posts qui contient tous les articles (posts dans la terminologie wordpress) dans un mélange de markdown + html brut (ce qui n’aura pas été correctement converti, on y reviendra)
un dossier wp-content qui contient tous les médias
des dossiers pour chacune de vos “pages (“à propos”, “mentions légales”, etc).

Importer dans Hugo

L’arborescence de Hugo est elle un peu différente. De base, tout ce qui est markdown doit être dans content, avec des sous dossiers en fonction du type de page (post ou page).

La première petite “blaguounette” est que les posts doivent être déposés dans le sous-dossier content/post (sans S à la fin !!!).

Chaque post commence par des métadonnées encadrées par des triples tirets “—” avant et après. Ca donne quelque chose comme ça :

---
title: 'ESXi 4.0 : Explorons l&rsquo;Hidden Console Part 1'
authors:
 - zwindler
type: post
date: 2010-04-28T08:32:20+00:00
url: /2010/04/28/esxi-4-0-explorons-lhidden-console-part-1/
featured_image: https://blog.example.org/wp-content/uploads/2014/10/vmware-220x162.jpg
categories:
 - Virtualisation
tags:
 - ESX(i)
 - Hidden Console
 - SSH
---

[L'article lui même...]

Ca peut différer un peu selon les thèmes je pense, mais grosso modo les markdown des pages iront eux dans content/page.

Enfin, tout ce qui est media (dossier wp-media) va dans un dossier static. On peut garder la même arborescence que wordpress (/année/mois/) mais rien ne nous y oblige.

So far, so good

Emile et Images

Enfin… so good, c’est vite dit…

Et oui parce que l’exporter n’exporte pas hyper bien un certain nombre de choses, à commencer par l’image de garde de chaque article :

featured_image: https://blog.example.org/wp-content/uploads/2014/10/vmware-220x162.jpg

On peut remarquer plusieurs soucis avec cette variable. D’abord, la variable utilisée pour indiquer le chemin de l’image dans les métadonnées générées est featured_image alors qu’Hugo attend image. Petit sed sur vos md pour corriger ça :

sed -i "s/featured_image/image/g" fichier.md

Mais bien sûr, ce n’est pas fini ;-)

Ensuite, on remarque qu’on a un chemin est une URL complète et non pas relative. Si vous gardez les média dans le chemin static/wp-content/uploads/YYYY/MM ça marchera, mais je trouve ça moche.

2 solutions :

on supprime /wp-content/uploads avec un bête sed -i "s!/wp-content/uploads!!g fichier.md
on passe en relatif en supprimant carrément toute la première partie de l’URL https://yourblog.example.org/wp-content/uploads

Si vous choisissez la 2ème solution (mon choix), faites quand même bien attention. En fonction de comment vous rédigez votre expression régulière, ça pourrait affecter aussi toutes les autres images que vous auriez en lien dans vos articles. Ce n’est pas forcément une mauvaise chose (moi j’aime mieux les liens relatifs car c’est plus flexible) mais ça demande un travail supplémentaire.

Images intermédiaires

Toujours dans les images, vous remarquerez aussi que l’image “mise en avant” (dans les métadonnées) possède un suffixe de type -111x222 juste avant l’extension. En fait, chaque fois que vous importez une image dans wordpress, celui ci la convertie en plusieurs tailles pour accélérer le chargement des pages.

Sauf que le wordpress-to-hugo-exporter choisi une des plus petites résolution pour l’image en tête de l’article. Ca sera souvent hyper moche…

Là encore, j’ai donc passé un gros sed pour virer tous les suffixes -111x222 avant l’extension, puis je n’ai copié QUE les images originales dans le dossier static (regex non triviale) :

cd PATH_TO_EXPORT/wp-content/uploads
for i in `seq 2010 1 2021`; do
 find $i -mindepth 1 -type f -regextype posix-egrep -not -iregex ".*/.*-[0-9]{1,4}x[0-9]{1,4}.*\..*" -exec cp {} PATH_TO_HUGO/static/{} \;;
done

Nettoyer les caractères spéciaux HTML

Si vous avez bien lu l’exemple de métadonnées exportées que j’ai donné, vous aurez peut être remarqué la présence d’un caractère spécial encodé ’ dans le titre.

Dans une page HTML, ce n’est pas grave, mais Hugo lui, ne les interprète pas comme tel dans le markdown. Il faut donc leur faire la chasse et tous les convertir 🤦. Et encore, il faut faire attention, car certains de ces caractères pourraient être légitimement écris en HTML (si vous faite un tuto sur HTML, ce n’est pas impossible par exemple)…

J’ai pour ma part lancé un gros sed (une fois de plus) sur tous mes articles mais prudence !

sed -i "s/&rsquo;/’/g" $1
sed -i "s/&#8211;/--/g" $1
sed -i "s/&#8230;/.../g" $1
sed -i "s/&gt;/>/g" $1
sed -i "s/&lt;/</g" $1
sed -i "s/&#8212;/-/g" $1
sed -i "s/&#8217;/'/g" $1
sed -i "s/&#215;/×/g" $1

Je n’ai pas osé modifier les caractères suivants, très souvent présents dans les URLs :

&#038
&#039
&quot;

Mais c’est quand même une bonne idée de faire une grosse recherche avec votre éditeur de texte favori pour voir s’il ne reste pas des &# qui traînent dans votre contenu.

HTML désactivé

Au delà des caractères spéciaux, il arrive aussi que l’exporter est un peu de mal avec les différents types d’éditeurs que Wordpress a pu avoir au fil du temps.

Typiquement, beaucoup du contenu “non texte” que j’ai ajouté au fil des années s’est retrouvé non converti par ce que j’ai rédigé s’est retrouvé exporté tel quel, en HTML brut inséré dans mon markdown.

C’est hyper traître car Hugo ne renvoie aucune erreur. Il manque “juste” des bouts ! On peut les retrouver en allant voir le code source de la page, qui affiche alors les commentaires HTML suivants :

<!-- raw HTML omitted -->

En attendant de nettoyer tout ça à grand coup de sed, on peut résoudre une partie des problèmes en “réactivant le support du code HTML dans le markdown dans votre config.yaml.

markup:
 goldmark:
 renderer:
 ## Set to true if you have HTML content inside Markdown
 unsafe: true

Ca permet de sauver les meubles mais ce n’est pas suffisant…

Markdown hates HTML

Même comme ça, on grosse partie du HTML sera HS… Tous les tableaux (table/tr/td) et listes (ul/li) HTML sont pétés car l’exporter laisse des sauts de lignes entre les blocs, que le markdown interprète mal. Il faudra supprimer tous les sauts de lignes en trop (ou réécrire en markdown)

<table class="Content" border="0" width="750">
<tr>
<td class="LargeBold">
SEND_CUSTOM_SVC_NOTIFICATION
</td>
</tr>
<tr>
<td class="MediumBold">
Command Format:
</td>
</tr>

Sachez également que toutes les “videos embedded” Youtube disparaîtront purement et simplement, et que pour les tweets, vous aurez une version très moche du tweet, sans l’image…

<blockquote class="twitter-tweet" data-width="550" data-lang="en" data-dnt="true" data-partner="jetpack">
 <p lang="fr" dir="ltr">
 [[#SAPHANA](ht tps://tw itter.com/hashtag/SAPHANA?src=hash&ref_src=twsrc%5Etfw)] Finies les mises à jour incompatibles avec votre plateforme, optez pour la simplicité et la tranquillité, chez SAP : on collecte, on connecte, ça marche : [t.co/2AdCCEQ97L](https://t.c o/2AdCCEQ97L) [pic.twi tter.com/yy7moMnZmC](ht tps://t.c o/yy7moMnZmC)
- SAP France (@SAPFrance)

 [October 8, 2018](ht tps://twiter.com/SAPFrance/status/1049286253533962241?ref_src=twsrc%5Etfw)
</blockquote>

J’en avais peu heureusement, j’ai donc pris des captures d’écran et ajouté des liens.

Balises de code, pre, etc.

Une autre grosse catégorie de code “mal exporté” est le “code”. Je donne souvent des bouts de scripts ou de code ou tout simplement des commandes à passer sur des serveurs. Et au fil des années, j’ai (& wordpress) changé plusieurs fois la façon d’afficher du code dans mes articles.

D’abord avec des balises HTML <pre></pre>, puis des balises <code></code>, puis via des extensions (pour avoir la coloration syntaxique), puis via du markdown via Jetpack, puis de nouveau via les extensions…

Autant dire que le HTML généré par Wordpress ne ressemble à rien…

Il a fallut faire un gros gros boulot pour détecter toutes les balises de code ouvrantes et fermantes pour les convertir en ``` de markdown…

Quelques exemples que j’ai rencontré :

<pre>

<pre class="brush: plain; title: ; notranslate" title="">
<pre class="brush: perl; collapse: false; title: ; wrap-lines: false; notranslate" title="">

<pre class="EnlighterJSRAW" data-enlighter-language="null">
<pre class="EnlighterJSRAW" data-enlighter-language="generic">
<pre class="EnlighterJSRAW" data-enlighter-language="generic" data-enlighter-theme="" >
... et bien d'autres encore

Final words

Je m’arrête là car l’article est déjà très long, mais il y a eu d’autres petits problèmes du même style, plus sporadiques…

Vous voyez donc qu’exporter le blog sur Hugo n’aura pas été de tout repos, dans mon cas. Et encore ! Je n’ai pas exporté les commentaires historiques (plus de 1600) !

Cependant, si vous avez un blog plus petit que celui ci, vous devriez avoir moins de mal et les conseils que je donne ici devraient vous permettre de régler rapidement 90% des problèmes.

Enjoy !

J'ai enfin migré de Wordpress vers Hugo - partie 1

Mon, 22 Nov 2021 08:00:00 +0000

Cette article fait partie d’une suite d’articles :

Plus de 2 ans et demi

Ca fait plus de 2 ans et demi que je râle que j’en ai ma claque de Wordpress.

Stack LEMP à maintenir, perfs bof (j’ai du mettre un cache pour passer sous la seconde, wtf…), plugins aux MAJs hasardeuses, failles de sécu, pas de support propre du markdown, éditeur à ch*** (Gutenberg, je te hais), … you name it.

Après 12 ans de blogging, il était temps de faire l’effort et de quitter Wordpress pour quelque chose qui me convient mieux : un moteur de blog statique (rien de dynamique dans ce que je poste) en markdown (parce que de toute façon c’est comme ça que j’écris mes articles à la base). Le tout dans git pour historiser tout ça.

Et j’ai choisi Hugo pour des raisons que je détaille dans l’article 2019 “Comment migrer de Wordpress à Hugo” si ça vous intéresse.

Forcément, c’est pas si facile

J’en parlais déjà dans l’article de 2019 : migrer de Wordpress à Hugo, forcément ce n’est pas si facile. D’ailleurs, j’avais même abandonné l’idée devant l’ampleur da tâche !

Ce n’est pas tant la partie technique (installation de Hugo, export du blog existant) le problème. En quelques minutes, on a un blog fonctionnel, l’export prend guère plus de temps. Rajouter l’outillage pour automatiser certaines tâches prend un peu de temps mais rien d’incroyable.

Mon problème était plutôt que je voulais obtenir au moins aussi bien que ce que j’avais avant, existant inclus.

Et c’est là que le bat blesse : wordpress, avec mes 12 ans (350 articles) d’historique, c’est au fil des années 15 façons différentes d’afficher du HTML… que le plugin d’export gère comme il peut ! Nous y reviendrons.

Je vais donc vous guider un peu sur la partie technique, puis j’aborderai ensuite les points pénibles du nettoyage du markdown, qui m’a pris un bonne partie de mes vacances (plusieurs journées à ~2-3 heures par jour). Il y aura aussi, plus tard, des articles sur l’outillage à mettre en place pour se faciliter la vie au quotidien.

Installation

L’installation en elle même est triviale. On a un binaire compilé en go packagé dans un .deb (ou les sources si vous voulez le builder vous même) disponible sur github. Fin.

sudo apt update
sudo apt upgrade

export VER="0.88.1"
wget https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_${VER}_Linux-64bit.deb
# ou https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_extended_${VER}_Linux-64bit.deb
sudo apt install ./hugo*_0.88.1_Linux-64bit.deb

A noter que dans mon cas, je n’ai pas téléchargé la version ci dessus, mais la version “extended”, nécessaire pour le thème que j’ai choisi, mais le principe est le même.

Initialisation du site et du dépôt git

Hugo est maintenant disponible sur votre machine.

A partir de là, je vous invite fortement à versionner tout ce que vous allez faire avec votre blog. C’est bien entendu optionnel mais pourquoi se priver de toute la puissance du couple markdown + git ?

On commence par créer un dossier puis on génère un squelette de site vierge avec hugo new site :

mkdir hugo && cd hugo
hugo new site toto
Congratulations! Your new Hugo site is created in toto.
Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/ or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.

A partir de là, on va pouvoir initialiser notre dépôt git

cd toto
git init

Bon, si jamais vous lancez la génération du blog avec simplement la commande de preview hugo server, vous allez être assez déçus, ça donne une page blanche. Mais, ça marche !

hugo server
Start building sites …
hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio
WARN 2021/11/14 06:57:47 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2021/11/14 06:57:47 found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2021/11/14 06:57:47 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

 | EN
-------------------+-----
 Pages | 3
 Paginator pages | 0
 Non-page files | 0
 Static files | 0
 Processed images | 0
 Aliases | 0
 Sitemaps | 1
 Cleaned | 0

Built in 1 ms
Watching for changes in /toto/{archetypes,content,data,layouts,static}
Watching for config changes in /toto/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Ajout d’un thème

Avant même de commencer à ajouter du contenu, il est probable que vous allez vouloir choisir un thème. Il existe une liste de thèmes, plus fournie qu’en 2019, disponible ici.

Une fois le thème choisi, on va l’ajouter au site à l’aide de la (très utile) commande git git submodule qui va nous permettre de gérer notre thème et ses mises à jour avec git sans pour autant commiter tous les fichiers.

Dans mon cas j’ai choisi le thème “stack” mais le principe est grosso modo le même pour tous (à quelques détails d’implémentation près) :

cd themes/
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git
cd ..

Avant le premier article !

Si on veut bosser un peu proprement, on va vouloir éviter de commiter n’importe quoi. Comme hugo est un générateur de blog statique, on va bien entendu éviter de commiter le code statique généré par la commande hugo.

On utilise simplement un fichier .gitignore à la racine du projet pour ignorer tout ce qui est technique ou qui n’est pas du code :

cat > .gitignore << EOF
themes
resources/_gen
assets/jsconfig.json
public
EOF

On va aussi vouloir paramétrer a minima notre site. Vous aurez peut être remarqué qu’il existe un fichier config.toml généré par défaut par la commande hugo new site. Il s’agit de “l’ancienne” manière de faire de la configuration Hugo, mais surtout d’un fichier agnostique du thème utilisée. Généralement, il vaut mieux le supprimer et repartir du fichier d’exemple inclus avec votre thème.

Dans mon cas, il s’agit du fichier theme/hugo-theme-stack/config.yaml que j’ai donc copié à la racine du projet et modifié pour correspondre à mon site et mes besoins.

baseurl: https://blog.zwindler.fr
languageCode: fr-fr
theme: hugo-theme-stack
title: "Zwindler's Reflection"
[...]

Le premier commit

C’est un petit moment agréable dans n’importe quel projet informatique. Le premier commit.

Bon moi, comme j’ai hébergé le dépôt sur Github et qu’ils ont décidé de renommer master en main dans le nom de la branche par défaut on a un peu de gymnastique à faire, mais pourquoi pas.

git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:zwindler/example.org.git
git push -u origin main

Le “code” de notre (absence de) blog est publié Internet :)

Et en prod ?

Vous pouvez donc commencer à écrire (dans content/post), tester votre blog en local, puis pousser le code sur git. Mais si jamais vous voulez héberger votre site ailleurs que sur votre laptop (et je parie que c’est le cas) ?

Et bien c’est là où c’est chouette d’utiliser git et un dépôt accessible depuis Internet. Vous n’avez qu’à reproduire l’installation de hugo, ajouter votre dépôt, initialiser les submodules (notre thème) et le tour est joué !

export VER="0.88.1"
wget https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_${VER}_Linux-64bit.deb
# ou https://github.com/gohugoio/hugo/releases/download/v${VER}/hugo_extended_${VER}_Linux-64bit.deb
sudo apt install ./hugo*_0.88.1_Linux-64bit.deb

git clone https://github.com/zwindler/toto.git
git submodule init
git submodule update

hugo

Normalement, le site devrait se générer, comme en local. Si vous n’avez pas d’historique à migrer, comme moi, vous êtes donc l’heureux propriétaire d’un blog statique fonctionnel :-). La classe !

Sinon, dans le prochain article, j’aborderai un plus gros morceau, à savoir l’export et le nettoyage du markdown depuis un Wordpress existant.

Comment migrer de WordPress à Hugo

Mon, 10 Jun 2019 11:35:20 +0000

Mais c’est qui ce Hugo ?

Dans la rétrospective des 9 ans / 250ème articles sur le blog, je vous ai parlé de mes futurs projets.

Une bonne partie des projets concernent le blog lui-même, en particulier abandonner WordPress et passer à un blog statique.

Car les reproches que je fais à WordPress sont nombreux :

Une techno d’un autre âge, d’une lenteur infernale dès qu’on commence à avoir un peu de contenu
Besoin de nombreux plugins pour avoir un rendu correct pour un blog tech, pour le partage, les stats, l’antispam, les protections/firewall, des jolies balises pour les bouts de code, …
Des sauvegardes BDD + plugins + média à paramétrer (et complexes à tester)
Des caches à mettre partout pour éviter que la moindre page avec quelques images mette 5 secondes à charger…
Gutenberg, le nouvel éditeur qui par défaut vous fait écrire sur 550 px de large (1/5ème de mon écran, à peine plus large qu’une carte de visite)

Bref, j’en ai marre

Alors je le suis dis : pourquoi j’ai un bousin infâme qui fait le café (franchement ça fait tout et n’importe quoi WordPress, du e-commerce au CV interactif) alors que moi, j’ai juste besoin d’un bidule où je peux écrire mes bêtises, que ça soit lisible sans avoir besoin de mettre un cache en frontal et éventuellement qu’on puisse me laisser un commentaire pour me remonter une coquille (ou juste discuter) ?

En gros, un site web statique avec un bon éditeur de texte quoi…

Les sites statiques, c’est fantastique

Alors c’est sûr, on peut aussi écrire le HTML/CSS soit même. Mais bon, avoir une application pour nous mâcher le travail et n’avoir que le contenu à gérer, c’est quand même plus sympa.

Quand j’ai commencé à m’y intéresser, un nom revenait souvent : Jekyll (et Ghost encore avant). Mais je n’ai jamais sauté le pas. Mais depuis, un petit nouveau fait parler de lui. Et comme d’autres, j’ai voulu tester Hugo pour remplacer WordPress. Hugo est un moteur de blog statique écrit en Go. Il a plutôt le vent en poupe et est assez simple à prendre en main.

C’est open source donc je peux l’auto-héberger de façon pérenne (coucou les gens qui postent une vie de travail sur Medium). Mais bien plus encore que ca, le contenu, c’est juste du Markdown. On a donc un site entièrement réversible au cas où Hugo viendrait à disparaître.

La syntaxe utilisée (Markdown, je viens de le dire) est archi connue et relativement simple à prendre en main. D’ailleurs, on peut très bien utiliser des blocs Markdown avec Jetpack dans WordPress pour écrire ses articles.

Tu te moques pas un peu de nous ?

Depuis le début, je vous dis que WordPress c’est tout moisi et que Hugo ça a l’air trop cool. Mais ce site… est encore sous WordPress !

Pour être honnête, c’était plus difficile à migrer que je le pensais, d’où cet article. A date, j’ai une copie du blog en ligne sous Hugo (EDIT : Down maintenant), qui fonctionne, mais pas totalement isopérimètre en terme de fonctionnalités. Je vais donc laisser vivre en parallèle les deux versions, le temps que je fixe tout ce qui manque.

Mais en attendant, je vous propose de me suivre pour cette merveilleuse aventure : Migrer de WordPress vers Hugo.

Installation

A en croire le site, c’est hyper simple !

C’est comme toutes les docs d’installs en page principale d’un site pour un logiciel open source, c’est simple mais en fait ça marche jamais (du premier coup). Fou cette coïncidence ! ;-P

gohugo.io/getting-started/installing/

Prérequis

Les prérequis sont en effet plutôt simples. Sous Debian/Ubuntu :

apt-get update
apt-get upgrade
apt-get install git python-pip
pip install Pygments

On va ensuite chercher le numéro de la dernière release sur le site github.com/gohugoio/hugo/releases puis on la wget + dpkg -i comme des cochons :

export VER="0.54"
wget https://github.com/gohugoio/hugo/releases/download/v${VER}.0/hugo_${VER}.0_Linux-64bit.deb
dpkg -i ./hugo_0.54.0_Linux-64bit.deb

Initialiser le site

Ok, pour l’instant, ils ne nous ont pas trop menti. Ça a l’air simple. On peut initialiser un nouveau site simplement avec la commande hugo new site. Puis ensuite, on peut versionner / sauvegarder blog et tout son contenu avec un dépôt git :

mkdir hugo && cd hugo
hugo new site blog.zwindler.fr
git init

Trouver un thème

Un des soucis que j’ai avec Hugo (mais avec WordPress aussi alors je suis peut-être juste quelqu’un de pénible ?), c’est de trouver un thème.

Je veux un thème de blog (mais qu’est ce que vous avez tous à faire du e-commerce avec des moteurs de blog!!!), avec une colonne centrale assez large pour que les bouts de codes/lignes de commandes soient lisibles, avec la possibilité de mettre une image en avant sur la page d’accueil.

themes.gohugo.io/

Personnellement, le thème qui se rapproche le plus de ce que j’ai aujourd’hui, c’est le thème aether, auquel j’ai apporté quelques modifications. Pour ajouter un thème, le plus propre est d’utiliser la encore git, via la fonctionnalité des submodules.

Je vous donne mes modifs personnelles sur ce thème (colonne centrale plus large, modification de la taille des images sur la page d’accueil) mais cette étape n’est absolument pas nécessaire.

diff ./themes/aether/assets/css/style.css.ori ./themes/aether/assets/css/style.css
25c25
< max-width: 50rem;
---
> max-width: 60rem;
165c165
< max-width: 49rem;
---
> max-width: 59rem;
419,420c419,421
< height: 100%;
< width: 15em;
---
> height: 83%;
> padding: 1.5em 0em;
> width: 20em;

Configurer le site

Maintenant qu’on a initialisé le site et choisi un thème, on peut commencer à configurer le site et le thème. En effet, de nombreux paramètres dépendent du thème que vous aurez choisi et des fonctionnalités qu’il intègre. Je ne peux donc que vous donner un exemple :

Dans le fichier config.toml à la racine du site, voici ce qui a été paramétré

baseURL = "https://blog.example.org/"
languageCode = "fr-fr"
title = "Zwindler's Reflection"
theme = "aether"
disqusShortname = "zwindler"
[params]
brand = "Zwindler's Reflection"
description = "Ma vie parmi les lol-cats || Je mine des bitcoins dans mon garage"
homeimg = "./wp-content/uploads/2019/05/servers.jpg"

De plus, pour ajouter la coloration syntaxique sur les partions de code, il faut ajouter dans la conf les deux paramètres suivants :

pygmentsCodefences = true
pygmentsStyle = "pygments"

Puis lancer la commande suivante :

hugo gen chromastyles --style=monokai > themes/aether/assets/css/syntax.css

Extraire les données de WordPress

OK ! Notre site est paramétré. Si vous êtes sur cet article simplement pour découvrir Hugo, vous avez déjà un blog fonctionnel. Il ne reste plus qu’à écrire du contenu et générer le code statique.

cependant, dans mon cas, j’ai parlé depuis le début de migrer depuis WordPress. Je pars donc du principe que, comme moi, vous avez de nombreux articles (et éventuellement commentaires) que vous souhaitez conserver. Il serait dommage de devoir repartir de 0.

Heureusement, il est possible de récupérer les données existantes d’un WordPress pour les réimporter dans Hugo. Le site officiel liste les options possibles et notamment un plugin qui converti les articles (et éventuellement les commentaires sous les articles) en Markdown.

Tout simplement (enfin… n’exagérons rien).

wordpress-to-hugo-exporter

Je suis donc parti sur le projet wordpress-to-hugo-exporter, qui est une extension native à WordPress permettant de réaliser cet export “en un clic”.

La première chose à faire pour installer cette extension est de vérifier que votre serveur qui héberge le WordPress dispose bien de l’extension PHP zip.so.

Si c’est bien le cas, on peut cloner le projet git directement dans le dossier plugin de WordPress

cat /etc/php.d/40-zip.ini
; Enable ZIP extension module
extension=zip.so
cd /var/www/html/wp-content/plugins/
git clone https://github.com/SchumacherFM/wordpress-to-hugo-exporter

Il nous faut plus de ziggourats RAM

Ça arrive tout le temps… Il n’est pas rare que les processus de ce genre (export/import/package de sauvegarde) nécessitent une grande quantité de RAM. J’avais déjà eu le souci avec Xwiki, je savais à quoi m’attendre ici.

Si vous aussi vous avez comme moi pas mal de contenu (250 articles, 500 Mo de media), sachez que vous devrez probablement augmenter les tailles mémoires autorisées par WordPress dans le fichier wp-config.php.

// Set initial default constants including WP_MEMORY_LIMIT, WP_MAX_MEMORY_LIMIT, WP_DEBUG, SCRIPT_DEBUG, WP_CONTENT_DIR and WP_CACHE.
wp_initial_constants();
define( 'WP_MEMORY_LIMIT', '2048M' );
define( 'WP_MAX_MEMORY_LIMIT', '2048M' );

De même, le temps que le processus d’export arrive à son terme, votre page web sera peut être partie en timeout. Deux possibilités dans ce cas.

Soit vous exécutez l’export depuis la ligne de commande

cd wp-content/plugins/wordpress-to-hugo-exporter/
This is your file!
/tmp/wp-hugo.zip
php hugo-export-cli.php
#ou pour s'affranchir des limites RAM en même temps
php hugo-export-cli.php memory_limit=-1

Dans tous les cas, vous devriez finir par obtenir un ZIP, contenant tous vos articles et toutes vos pages, au format Markdown. Le contenu de ce ZIP est à déposer dans le sous dossier content de votre arborescence de blog Hugo :

unzip wp-hugo.zip
cd hugo-export
cp -r posts wp-content ~/hugo/blog.zwindler.fr/content/

Nettoyage du markdown

Ca y est ? On peut générer le site statique maintenant ?

Et bien non… pas encore. En fait, le processus d’export de WordPress vers Markdown n’est pas parfait.

J’ai du “nettoyer” le code Markdown pour que le résultat soit enfin acceptable.

La première chose, difficilement compréhensible, est que s’il y a bien les données correspondant à l’image “mise en avant” pour chacun de nos article, le nom de la variable est image alors qu’Hugo attend le nom image.

On peut régler ça avec un bête “sed”

find . -name "*.md" -exec sed -i "s/featuredImage/image/g" {} \;

Par défaut, toutes les images de wordpress sont réduites dans plusieurs tailles, pour optimiser les temps de chargement. Cependant, dans l’export, on se retrouver avec des vignettes très petites, difficilement lisibles.

Pour me simplifier la vie, j’ai utilisé cette commande pour remettre les images en taille complète. Attention cependant, cela peut avoir un impact important sur les temps de chargement des pages si vous avez de très grandes images…

find . -name "*.md" -exec sed -i 's/-220x162//g' {} \;

Un des problèmes que j’ai avec l’éditeur de WordPress, c’est justement qu’il réencode tous les caractères spéciaux avec leurs codes HTML. D’un point de vue lecture de texte simple, ça ne pose souvent pas de problème. Cependant pour tout ce qui est scripts et bouts de code, ça génère très souvent des erreurs.

Voici une liste des caractères que j’ai remplacés dans mon Markdown. Attention cependant, il pourrait que cela remplace des caractères spéciaux que vous auriez légitimement (pour une raison qui m’échappe) encodé en HTML

find . -name "*.md" -exec sed -i "s/>/>/g" {} \;
find . -name "*.md" -exec sed -i "s/</</g" {} \;
find . -name "*.md" -exec sed -i "s/&/&/g" {} \;
find . -name "*.md" -exec sed -ie "s/ /\n/g" {} \;
find . -name "*.md" -exec sed -i "s/–/–/g" {} \;
find . -name "*.md" -exec sed -i "s/—/—/g" {} \;
find . -name "*.md" -exec sed -i "s/…/…/g" {} \;
find . -name "*.md" -exec sed -i "s/″/″/g" {} \;
find . -name "*.md" -exec sed -i "s/′/″/g" {} \;
find . -name "*.md" -exec sed -i "s/«/«/g" {} \;
find . -name "*.md" -exec sed -i "s/»/»/g" {} \;
find . -name "*.md" -exec sed -i "s/’/’/g" {} \;
find . -name "*.md" -exec sed -i "s/‘/‘/g" {} \;

J’ai aussi trouvé les caractères suivants, que je n’ai pas osé réencoder de peur de casser des URLs :

&#038
&#039
"
'

Et pour finir, dans WordPress, j’utilisais dans WordPress un plugin qui entourait mes bouts de code de balises HTML pre pour afficher du code avec la coloration syntaxique.

Dans Hugo, les balises sont celle de markdown. Voici donc la commande pour convertir les balises pre en balise de code Markdown

find . -name "*.md" -exec sed -ie "s/<pre.*>/\n\`\`\`\n/g" {} \;
find . -name "*.md" -exec sed -ie "s/<\/pre>/\n\`\`\`\n/g" {} \;

Tester le blog

Voila !!! Vous pouvez enfin tester votre blog, avec votre contenu Markdown. Hugo propose un serveur web que vous pouvez utiliser localement pour vous assurer que tout vas bien avant d’uploader votre site statique.

Il n’est évidement pas question d’utiliser ce mode en production. Il s’agit seulement d’un mode “preview”.

$ hugo server
Start building sites …
hugo v0.88.1-5BC54738+extended linux/amd64 BuildDate=2021-09-04T09:39:19Z VendorInfo=gohugoio
| FR
-------------------+-------
Pages | 3234
Paginator pages | 354
Non-page files | 0
Static files | 0
Processed images | 1
Aliases | 1439
Sitemaps | 1
Cleaned | 0
Built in 4895 ms
Watching for changes in /home/zwindler/sources/hugo/blog.zwindler.fr/{assets,content,data,layouts,static,themes}
Watching for config changes in /home/zwindler/sources/hugo/blog.zwindler.fr/config.yaml, /home/zwindler/sources/hugo/blog.zwindler.fr/themes/hugo-theme-stack/config.yaml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Sauvegarder/générer/déployer le site

Si après vérification, votre blog vous convient, vous n’avez alors plus qu’à “sauvegarder” votre site via git.

Vous pouvez ensuite générer le site statique en invoquant simplement la commande hugo

$ hugo
| EN
+------------------+-------+
Pages | 2634
Paginator pages | 231
Non-page files | 10951
Static files | 73
Processed images | 0
Aliases | 1187
Sitemaps | 1
Cleaned | 0
Total in 5555 ms

Les pages statiques seront générées et sauvegardées dans le sous dossier public. Vous pourrez enfin simplement copier ce dossier sur n’importe quel serveur web (voire même des blobs sur un cloud provider) et vous aurez votre site statique !!!

Enjoy !

Fusionner plusieurs dépôts Git tout en gardant l’historique

Fri, 24 Mar 2017 13:00:31 +0000

Je découvre Git

L’avantage de travailler en #DevOps (et c’est d’ailleurs tout le principe), est que la proximité avec les Devs (et inversement les Ops) incite à comprendre les méthodes de travail et à utiliser les outils des autres. Et bien sûr, en cas de difficulté, je n’ai qu’à me retourner et demander un coup de main aux experts ;-). Dans mon exemple, j’avais un petit souci avec Git.

J’avais initialement stocké des playbooks Ansible dans des dépôts Git distincts et bien sûr quand j’ai commencé à en avoir beaucoup (~20) j’ai changé d’avis. Cela devenait trop contraignant à exploiter sachant que les playbooks (découpés en rôles) sont parfois interdépendants.

Le plus simple aurait été de regrouper l’ensemble des sources à la version actuelle dans un même dossier, puis de tout simplement recréer un dépôt. Cependant, de cette manière, je perdais l’ensemble de l’historique des commits. Idem si j’avais copié les fichiers dans un des dépôts existant (je n’aurai gardé que l’historique d’un seul dépôt).

N’étant pas expert Git, il y a probablement plusieurs façon, cependant, je peux attester que celle a fonctionné dans mon cas ;-).

Regarder comment Git fonctionne

Je ne vais pas vous faire un cours pour vous expliquer comment Git fonctionne, il existe de nombreuses ressources qui mettent en avant les avantages de Git par rapport à d’autres logiciels de gestion de version.

Note : Si vous débutez sur ce VCS, je vous conseille vivement de commencer par dérouler un tutoriel pour comprendre les bases et pourquoi par faire quelques tutoriels interactifs (sous la forme de petites « énigmes »). Je donne quelques exemples en fin d’article.

Je me contenterais simplement rappeler que Git est un logiciel de gestion de version qui, à la différence de SVN, n’a pas de serveur centralisé. Ce point, pas forcément intuitif si vous venez de SVN, est extrêmement important.

Au delà du fait que ce caractère décentralisé est un des points qui a fait la popularité de ce VCS, cela va nous permettre de régler mon problème :

je vais créer un nouveau dépôt vierge
lui ajouter l’URL dans sa configuration les dépôts existants en tant que remote, lui faisant croire que ce sont des dépôts provenant du même code source
recréer artificiellement entre les deux dépôts un historique « commun » avec git rebase

Au travail maintenant

La première étape consiste donc à créer un nouveau dépôt git. Créez un dossier vide, mettez vous dedans et initialisez un nouveau dépôt grâce à la commande suivante :

git init #pour créer un nouveau repo dans le dossier courant

Que fait Git ?

Et bien dans le cas présent, il se contente de créer un dossier .git dans lequel il stockera ses métadata, ainsi qu’un fichier config dans lequel on retrouve toutes les options du dépôt. Ouvrez le avec votre éditeur de texte préféré, voilà à quoi ça devrait ressembler :

[core]
repositoryformatversion = 0
filemode = false
bare = false
logallrefupdates = true
symlinks = false
ignorecase = true
hideDotFiles = dotGitOnly

On va donc maintenant y ajouter les URLs des dépôts en tant que « remotes ». Dans mon cas, les dépôts sont accessibles via des URL HTTPS via Gitlab, mais ce n’est aucunement un prérequis. Vous devez juste pouvoir renseigner les « remotes » dans votre fichier .git/config.

[remote "depot_ansible_1"]
url = https://@IPgitlab/automatisation/depot_ansible_1.g1t
fetch = +refs/heads/*:refs/remotes/origin/*
[remote "depot_ansible_2"]
url = https://@IPgitlab/automatisation/depot_ansible_2.g1t
fetch = +refs/heads/*:refs/remotes/origin/*
[remote "depot_ansible_3"]
url = https://@IPgitlab/automatisation/depot_ansible_3.g1t
fetch = +refs/heads/*:refs/remotes/origin/*

Dans l’exemple suivant, j’ai donc ajouté des dépôts, nommés depot_ansible_1, depot_ansible_2 et depot_ansible_3, tous accessibles depuis mon Gitlab aux URLs données.

Comme on part d’un dépôt vide, le premier git pull vers depot_ansible_1 devrait bien se passer. Git se contente d’intégrer l’ensemble du code et des commits du dépôt depot_ansible_1 comme si on avait fait un « clone ».

git pull depot_ansible_1 master

So far, so good

Ca se complique « un peu »

Évidemment on ne peut plus reproduire la manœuvre précédente. Si vous tentez de le faire, vous recevrez un message qui vous dira que les deux dépôts ne partagent pas d’historique commun. On va donc faire un pull avec l’option rebase. Mais avant tout un petit coup d’œil au man.

Dans mon cas, c’est précisément ce que je souhaite faire. Pour autant, je vous engage moi aussi à faire attention ;-).

git pull -r depot_ansible_2 master

A partir de ce moment là, git tente de trouver un point commun entre les deux arbres des 2 premiers dépôts (potentiellement jusqu’à l’initialisation du dépôt), puis recréée un historique à partir des deux dépôts en rejouant un à un les commits des deux dépôts.

Un dernier point, si vous tombez, lors du rebase, sur un conflit, vous devez le résoudre manuellement. Ajoutez les fichiers corrigés avec « add », puis continuez avec « rebase –continue »

C’est fini, on nettoie un peu

Mission accomplie pour ces deux dépôts, qui sont maintenant fusionnés dans un seul dépôts avec leurs historiques de commits respectifs ! Vous n’avez plus qu’à reproduire la procédure pour chacun des dépôts (si vous en avez d’autre, depot_ansible_3 dans mon exemple).

Cependant, si vous avez des messages du genre « premier commit » dans chacun de vos dépôts, ces messages n’ont pas vraiment de sens. On peut donc réutiliser le principe du rebase pour réécrire une nouvelle fois l’historique. Le rebase vous proposera la liste des commits dans un éditeur et vous pourrez sélectionner manuellement ceux que vous voulez garder (pick) ou modifier (reword).

git rebase -i HEAD~X #puis sélectionner les commit à modifier et les corriger un à un

Par exemple, si j’ai 4 commits, et que je veux réécrire le 1er de depot_ansible_2

git rebase -i HEAD~3
pick 8c98724 commit 1 de depot_ansible_1
reword 5ad60bb commit 1 de depot_ansible_2
pick 82b0cc3 commit de depot_ansible_2
# Rebase dff1fb2..82b0cc3 onto dff1fb2 (3 command(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# [...]

Documentation complémentaire

Automatiser la création d’une image Dockerhub

Tue, 24 Jan 2017 13:00:53 +0000

Créer un automated build sur le Dockerhub

Ça fait quelques semaines maintenant que j’ai mis à disposition sur le Dockerhub ma première image Docker. Sans aller jusqu’à dire qu’elle a déplacé les foules, je suis assez content de voir que je ne suis pas le seul à l’utiliser avec une 100aine de « pull », même si sur le segment des images préconfigurées pour XWiki, les builds de Hellyna et Lavadiablo sont bien plus souvent téléchargées. Et c’était sans compter sur l’image Docker officielle de XWiki qui est sortie juste avant que je ne publie cet article !

Mais aussi auto-satisfait que je suis, je suis forcé de le reconnaître, cette image Docker pêche d’un défaut de jeunesse : la mise à disposition d’une nouvelle version nécessite :

Que je modifie (et éventuellement que je le push sur Github) mon code sur mon repository git
Que je la build moi même à partir du code

docker build -t zwindler/xwiki-tomcat8:latest .

Et une fois l’image sur mon Docker registry local, que je lance la commande

docker push zwindler/xwiki-tomcat

Mais, vous l’aurez deviné, il y a mieux ;-)

Une fonctionnalité de Dockerhub vous permet de créer une image que vous poussez manuellement ou une image dont la création est automatique. On peut distinguer ces deux types d’images par la mention automated build sous le nom de celle ci.

Comment en profiter ?

Tout commence d’abord par renseigner quelques informations dans votre profil. Dans les propriétés de votre compte, il y a un menu « Linked Accounts & Services ».

Ce menu vous permet de lier le Dockerhub avec un ou plusieurs comptes Github/Bitbucket via une autorisation de type OAuth.

Au delà de simplement lier les deux comptes, Dockerhub paramètre vos dépôts git et y ajoute des services (webhooks préconfigurés) permettant de prévenir automatiquement Dockerhub de la présence de code mise à jour sur GitHub.

On autorise l’accès en lecture/écriture sur le compte. On peut le mettre en lecture seule mais il faudra paramétrer les webhooks à la main !

Présence du service dans les paramètres du projet Github

Créer son premier automated build

Maintenant que les permissions sont bien passées entre Github et Dockerhub, on peut créer son image automatique.

Ici j’ai sélectionné mon compte Github, puis le projet qui contient mon projet xwiki-tomcat.

La suite de la création de l’image est similaire à la création d’une image « non automatique ». On donne un nom à l’image ainsi qu’une petite description et on valide en cliquant sur create.

Dans mon cas, ça n’a pas fonctionné du premier coup et le build a échoué car par défaut l’image cherchait le Dockerfile à la racine du projet Github. Sur mon dépôt git, le Dockerfile est situé dans un sous dossier, la racine contenant le README et un fichier docker-compose.

Dans ce cas précis, il faut donc aller dans le build settings et renseigner la variable « Dockerfile location ».

A noter : pour plus de clarté dans mes images, j’ai indiqué que la branche Master dans git correspondait au tag « latest » et ait ajouté une seconde ligne avec la branche Master taguée avec le numéro de version (actuellement 8.4.4).

Ainsi, les utilisateurs pourront soit récupérer la dernière version, soit spécifier la version 8.4.4 manuellement.

Et cerise sur le gâteau, j’ai également ajouté une branche 7.4.5-lts dans Github qui me permet de proposer de manière optionnelle une image préconfigurées avec la version LTS actuelle de XWiki.

Conclusion

Il est très simple de créer un automated build dans Dockerhub et vous avez donc tout intérêt à arrêter de pusher manuellement vos images si vous déposer votre code Github.com.

Seul bémol, le manque d’intégration avec Git ou même Gitlab qui sera un vrai point noir si vous avez votre propre dépôt personnel ou d’entreprise en dehors des deux services en lignes proposés par Dockerhub.

Sources

docs.docker.com/docker-hub/builds/

Installer XWiki 8.2.1 avec Docker (compose) en 2 lignes de commandes

Thu, 15 Sep 2016 11:00:28 +0000

Automatiser l’installation du XWiki avec Docker compose

Pour ceux qui ne le savent, XWiki est une plateforme collaborative de gestion de la connaissance (généralement appelé wiki, KMDB en ITIL). L’exemple le plus connu de wiki est bien entendu Wikipedia qui tourne par contre lui sous Mediawiki (un autre wiki, moins convivial mais très répandu). J’ai déjà écris pas mal au sujet du XWiki donc si vous voulez un petit tour d’horizon de ce qu’on peut faire avec, vous pouvez cliquer ici.

Je commence à en avoir installé un certain nombre :

que ce soit pour tester les nouvelles version
en recette ou en production pour de nouvelles équipes
faire des tests sur Docker

Si l’installation d’un XWiki est simplissime si vous utilisez les outils préconfigurés par défaut dans l’installeur JAR, l’installation d’une instance XWiki avec Tomcat et PostgreSQL est un peu plus complexe. Du coup, j’ai eu besoin à plusieurs reprise d’ouvrir mon propre tutoriel qui guide pas à pas l’installation de la version 7 de XWiki sur un Redhat Entreprise Linux 7 (ou CentOS).

Vous avez dit Docker ?

Et c’est notamment grâce au besoin que j’ai eu de faire des tests sur Docker que j’en suis venu à réaliser une image Docker XWiki.

XWiki était le parfait exemple pour s’initier à :

la création d’un service multi-conteneurs séparés par Tiers (Tomcat, PostgreSQL)
la rédaction d’un DockerFile qui automatise entièrement l’installation et la configuration de l’application java XWiki à partir de l’image standard Tomcat 8
l’ajout d’une orchestration de base avec Docker Compose
la mise en ligne d’une image publique avec Docker Hub

Un des avantages de Docker, c’est que grâce à l’aspect « portable » des conteneurs :

Avec ce conteneur, je peux garantir que les fichiers de configuration que j’embarque avec l’image seront compatibles.
Sans conteneur, avec un serveur Tomcat déjà existant et en fonction des fichiers de configurations embarqués selon telle ou telle distribution, les instructions que je donne dans mon article « pas à pas » pourraient ne pas toujours fonctionner.

Pour les plus pressés

Quelque soit la méthode que vous choisirez, le XWiki sera opérationnel et accessible sur le port 8080 à l’issue de ces commandes. Il faudra juste passer le « First Installation Wizard » et commencer à configurer le XWiki.

Avec Docker Compose

Docker compose se charge pour vous, à partir du fichier docker-compose.yml, de :

télécharger/builder l’image des conteneurs Postgresql et XWiki
configurer ces conteneurs
démarrer les conteneurs.

C’est donc forcément plus simple de le faire marcher en 2 lignes de commandes ;-).

[Edit]
A priori il n’est plus nécessaire de faire un « chmod +x xwiki-tomcat/xwiki-tomcat-entrypoint.sh » sinon ça ne fonctionne pas, j’ai corrigé les permissions sur le github
[/Edit]

git clone https://github.com/zwindler/docker-xwiki.git && cd docker-xwiki
docker-compose -f compose/docker-compose.yml up -d

Avec Docker depuis les sources

Avec Docker uniquement, il faudra forcément tout faire à la main. Donc il faudra créer le network, démarrer successivement l’image PostgreSQL puis l’image Tomcat modifiée par mes soins.

docker network create -d bridge xwiki-nw
docker run --net=xwiki-nw -itd --name xwiki-postgres -e POSTGRES_DB=xwiki -e POSTGRES_USER=xwiki -e POSTGRES_PASSWORD=xwiki postgres

git clone https://github.com/zwindler/docker-xwiki.git && cd docker-xwiki
chmod +x xwiki-tomcat/xwiki-tomcat-entrypoint.sh
docker build -t zwindler/xwiki-tomcat8:latest .
docker run --net=xwiki-nw -itd --name xwiki-tomcat -p 8080:8080 -e POSTGRES_INSTANCE=xwiki-postgres zwindler/xwiki-tomcat8

Avec Docker et Docker Hub

Un cran plus simple que la version précédente car je viens d’uploader l’image zwindler/xwiki-tomcat sur Docker Hub. Elle est donc automatiquement téléchargée depuis Docker hub lors de la commande docker run. Pas besoin de « chmod » ni de builder l’image.

docker network create -d bridge xwiki-nw
docker run --net=xwiki-nw -itd --name xwiki-postgres -e POSTGRES_DB=xwiki -e POSTGRES_USER=xwiki -e POSTGRES_PASSWORD=xwiki postgres
docker run --net=xwiki-nw -itd --name xwiki-tomcat -p 8080:8080 -e POSTGRES_INSTANCE=xwiki-postgres zwindler/xwiki-tomcat8

L’image en question

L’ensemble des sources sont disponibles sur Github dans mon repository docker-xwiki.

Voici le contenu du DockerFile :

FROM tomcat:8-jre8
MAINTAINER Denis GERMAIN <denis@example.com>
ENV POSTGRES_INSTANCE=xwiki-pgsql
ENV POSTGRES_PORT=5432
ENV POSTGRES_DB=xwiki
ENV POSTGRES_USER=xwiki
ENV POSTGRES_PASSWORD=xwiki
RUN rm -rf webapps/* && \
curl -L \
'http://download.forge.ow2.org/xwiki/xwiki-enterprise-web-8.2.1.war' \
-o xwiki.war && \
unzip -d webapps/xwiki xwiki.war && \
rm -f xwiki.war
RUN curl -L \
'https://jdbc.postgresql.org/download/postgresql-9.4.1208.jar' \
-o 'webapps/xwiki/WEB-INF/lib/postgresql-9.4-1208.jdbc42.jar'
COPY hibernate.cfg.xml webapps/xwiki/WEB-INF/
COPY xwiki.cfg webapps/xwiki/WEB-INF/
COPY setenv.sh bin/setenv.sh
RUN sed -i "s/redirectPort=\"8443\" /redirectPort=\"8443\" URIEncoding=\"UTF-8\" /" conf/server.xml
COPY xwiki-tomcat-entrypoint.sh /
ENTRYPOINT ["/xwiki-tomcat-entrypoint.sh"]

Des variables d’environnement ENV sont à votre disposition pour adapter à votre contexte (on en parlera un peu plus loin). La première étape consiste à télécharger la dernière version en date du XWiki, puis le pilote JDBC PostgreSQL correspondant.

Les fichiers de Tomcat sont adaptés pour un fonctionnement avec XWiki (Xmx java, autorisation des « / » dans les URLs, …) et les fichiers de configuration de XWiki sont paramétrés pour accepter l’instance PostgreSQL.

Personnalisation

Pour permettre un peu plus de souplesse dans l’utilisation de la base de données, j’ai volontairement ajouté des variables d’environnement et un script « ENTRYPOINT ». Ce script sert à paramétrer à la première exécution les valeurs définies en début de DockerFile (ENV).

Ceci permet à la fois de mettre à disposition une image Docker clé en main si l’utilisateur ne souhaite rien modifier et tout laisser par défaut, ou à l’inverse, de fournir des variables qui lui sont propres et personnaliser automatiquement son instance.

Vous pourrez ainsi par exemple changer le mot de passe et/ou le nom de l’instance PostgreSQL (soit via modification du docker-compose.yml, soit directement en modifiant le DockerFile).

Problème ALLOW_ENCODED_SLASH=true

Malgré l’ajout de ALLOW_ENCODED_SLASH=true dans catalina.properties, j’avais des problèmes pour ouvrir les pages avec des / dans les noms de pages.

J’en ai profité pour essayer de déplacer l’application du paramètres et l’intégrer au niveau du setenv.sh avec la variable d’environnement CATALINA_OPTS. Ca n’a pas corrigé le problème (situé à un autre niveau) mais a permis de simplifier le Dockerfile, ce qui est toujours bon à prendre.

En réalité, la variable était bien prise en compte dans les deux cas. Je l’avais vérifié et cela marchait depuis le début. En réalité, j’ai un reverse proxy Apache (ProxyPass) qui lui aussi fout le boxon avec les « / » dans mes titres de pages de XWiki.

La réponse suivante sur StackOverflow explique très bien ce qu’il se passe. Pour autant dans mon cas, impossible d’accéder à ces pages, quelque soit le paramètre essayé, dans le cas où le XWiki est derrière mon proxy Apache. Je peux y accéder sans, je vais donc devoir les renommer pour contourner le problème. De toute façon, ça ne me plait pas que ces pages aient un « / » dans leur URL ;-).