Avant d’attaquer la partie Docker, il est nécessaire de rappeler comment régler le fuseau horaire et l’heure de nos serveurs Linux, puisque finalement ce sont les mêmes méthodes que nous allons utiliser pour synchroniser nos containers Docker basés sur Linux.

Avant toute chose, voyons l’état de l’heure courante :

$ date
Tue Nov 17 15:26:20 CET 2020

Il y a deux choses importantes ici :

• Le fuseau horaire (timezone), ici CET pour Central European Time, l’heure de Paris pour faire court.
• L’heure en elle-même, qui peut être ou non bien synchronisée. À comparer avec par exemple celle-ci.

Pour changer le fuseau horaire sur Linux, c’est très simple, il suffit de lancer la commande suivante et de suivre les instructions:

dpkg-reconfigure tzdata

Pour synchroniser l’horloge avec la bonne heure, on utilise un service qui s’appelle NTP pour Network Time Protocol. Assurons-nous que le service est bien installé et activé dans systemd.

Adaptez ces commandes à votre OS, ici pour Debian 10.

apt install ntp
systemctl enable ntp
systemctl start ntp

Il n’est pas nécessaire d’installer ntp dans les containers Docker, parce que leur horloge est basée sur celle du host.

Bien, maintenant que nous avons couvert les bases, assurons nous que nos containers Docker aient une horloge synchronisé, soient sur le bon fuseau horaire, et arrêtent de décaler chaque élément.

Utiliser la configuration de la machine host

C’est la solution la plus simple pour caler l’heure de vos containers : s’appuyer sur l’heure et le fuseau horaire de la machine host, celle qui héberge le service Docker.

En revanche cette solution ne fonctionne que si vous avez la maîtrise du host, et elle n’est pas applicable si vous envoyez vos containers dans un quelconque solution cloud.

Pour cela, on va monter en lecture seule deux volumes sur les fichiers de configuration de l’horloge du host dans nos containers.

Dans un docker run, on ajoute deux volumes :

docker run -d \
   -v /etc/timezone:/etc/timezone:ro \  
   -v /etc/localtime:/etc/localtime:ro \
   [...]

Ou avec un docker-compose.yml :

services:
  service_name:
    volumes:
      - "/etc/timezone:/etc/timezone:ro"
      - "/etc/localtime:/etc/localtime:ro"

Régler le fuseau horaire des containers

Si la méthode précédente ne peut pas s’appliquer, parce que vous n’avez pas la main sur le host, ou s’il est nécessaire d’avoir des fuseaux horaires différents sur différents containers, alors il faut pouvoir régler la timezone directement dans l’image Docker.

Avant tout, pour Alpine Linux, le paquet tzdata n’est pas inclus par défaut, il est donc nécessaire de l’ajouter manuellement dans le Dockerfile :

RUN apk add --no-cache tzdata

Pour changer le fuseau horaire de nos containers Linux, plutôt que d’utiliser dpkg-reconfigure qui est interactif, on va utiliser une petite subtilité et faire la manipulation manuellement dans notre Dockerfile.

Ce que fait cette commande, c’est d’une part de mettre à jour le fichier /etc/timezone avec le bon fuseau horaire, mais aussi de créer une copie du binaire associé à la timezone dans /etc/localtime. Faisons donc ça :

FROM alpine  

ENV TZ=Europe/Paris 

RUN apk add --no-cache tzdata
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

Cette méthode fonctionne partout, et permet de définir directement la variable d’environnement TZ détaillée dans la section suivante.

Vous pouvez tester ça très facilement avec la commande :

docker build -t tzalpine . && docker run -it --rm tzalpine
$ date
# la date doit avoir le bon fuseau horaire ici

L’OS est maintenant à jour à l’intérieur des containers, quels que soit la configuration et l’environnement. Il ne reste plus qu’à s’assurer que les différents logiciels prennent bien en compte le fuseau horaire.

La variable d’environnement TZ

Une bonne partie des langages de programmation et/ou frameworks modernes s’appuient sur la même variable d’environnement : TZ. C’est le cas par exemple pour régler l’heure en Python et sur NodeJS.

En la définissant, et avec celle du système d’exploitation, vous devriez couvrir une bonne majorité des cas d’utilisation.

Attention toutefois, cette variable peut être généralement être surchargée, si c’est le choix des développeurs. Dans ces cas là, il y a généralement une option disponible dans la configuration de l’outil que vous utilisez, ou parfois dans son UI.

Il suffit de la définir au lancement de votre container :

docker run -d \
   -e TZ=Europe/Paris \
   [...]

Ou dans le docker-compose.yml:

services:
  service_name:
    environment:
      - TZ=Europe/Paris

Configuration PHP

Évidemment, PHP utilise un fonctionnement différent et ne prend pas en compte la variable d’environnement TZ.

Pour régler l’heure en PHP, il faut définir la valeur du paramètre date.timezone dans le fichier php.ini.

[Date]
; Attention à bien enlever le point-virgule, qui signifie commentaire.
date.timezone = Europe/Paris

Conclusion

Voilà, en principe on a fait le tour du sujet. J’ai mis à jour la plupart des mes containers pour qu’ils prennent en compte ces modifications, et tout semble rouler à la perfection.

Si jamais vous rencontrez des cas où les manipulations décrites dans cet article ne sont pas suffisantes, n’hésitez pas à me le faire remonter - je mettrais à jour ce guide.

Ressources :

• https://serverfault.com/questions/683605/docker-container-time-timezone-will-not-reflect-changes
• https://stackoverflow.com/questions/24551592/how-to-make-sure-dockers-time-syncs-with-that-of-the-host/
• https://docs.docker.com/engine/reference/run/
• https://docs.docker.com/engine/reference/builder/
• https://github.com/nodejs/help/issues/36
• https://help.pythonanywhere.com/pages/SettingTheTimezone/
• https://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone

Si vous n’avez pas vraiment suivi tout ça, je vous propose de faire un tour des nouvelles features, dans le désordre.

Les arguments nommés

Il est possible de passer les arguments d’une fonction ou d’une méthode en utilisant leur nom de variable, et de fait d’ignorer l’ordre de déclaration des paramètres. On retrouve un comportement similaire avec les arguments nommés de Python.

C’est très pratique, car cela permet également d’ignorer les paramètres facultatifs qui ne nous intéressent pas.

Par exemple pour faire une recherche où seule la casse nous intéresse :

function search(string $terms, $sortBy = 'dates', $caseSensitive = false) {}

// PHP 7.x
$results = search('my query', 'dates', true);

// PHP 8.0
$results = search(caseSensitive: true, terms: 'my query');

On voit clairement l’avantage dans cet exemple, le paramètre $sortBy n’a pas besoin d’être explicitement fourni, et donc on s’appuie toujours sur la valeur par défaut définie par la fonction elle-même. Le couplage est donc légèrement réduit.

Le contre-argument qui a été principalement présenté lors du vote de cette feature en revanche, c’est que l’on rajoute un lien fort sur le nom des paramètres, qui n’existait pas jusqu’alors. Il sera désormais plus difficile de renommer le nom d’une variable, en particulier dans les libraries.

Les attributs

LA feature attendue dans PHP 8.0 est clairement les attributs ; enfin, par moi en tout cas. C’est aussi ce qu’on appelle les annotations, par exemple en Java. Actuellement, la plupart des frameworks et libraries en PHP ont contourné le problème en utilisant des annotations via la PHPDoc, mais maintenant la fonctionnalité est officiellement supportée.

La syntaxe choisie est celle de Rust, c’est-à-dire : #[Attribute].

Exemple avec le routeur Symfony :

// PHP 7.x
class SomeController
{
    /** @Route("/path", name="action") */
    public function someAction() {}
}

// PHP 8.0
class SomeController
{
    #[Route('/path', name: 'action')]
    public function someAction() {}
}

Pour l’anecdote, les débats ont été assez virulents sur la meilleure syntaxe à choisir. En réalité celle retenue n’est même pas celle qui avait été votée en premier lieu. C’était à l’origine <<Attribute()>> qui avait été choisie, mais il s’est avéré que cette syntaxe posait des problèmes au niveau de l’implémentation au sein du langage.

De la même façon, il n’était pas possible de choisir @Attribute(), l’arobase étant déjà un caractère réservé en PHP (pour rendre les erreurs silencieuses, ne l’utilisez pas). L’autre option était @@Attribute().

Les types d’union

Les types d’union (union types) permettent de spécifier plusieurs types sur un même paramètre, retour de fonction/méthode, ou attribut de classe.

Cette fonctionnalité permet de peaufiner encore un petit peu la déclaration des types en PHP introduits en version 7.0, et qui ont déjà subi quelques améliorations depuis leur sortie (nullable, attributs, etc.).

Exemple :

// PHP 7.x
/**
 * @param int|float|null $threeshold
 * @return ArrayAccessImplementation|array
 **/
public function getListByPrice($threeshold) {}

// PHP 8.0
public function getListByPrice(int|float|null $threeshold): ArrayAccessImplementation|array {}

C’est évidemment à utiliser avec parcimonie, puisque l’avantage d’un typage strict des méthodes évite justement que l’on se retrouve avec n’importe quel type en entrée/sortie de celles-ci.

Note : inutile d’en faire une section complète ici, mais le type mixed a également été ajouté au langage, ce qui permet de ne plus jamais avoir de typage non défini, et simplifie grandement la vie des linters.

Déclaration des attributs dans le constructeur

Faute d’une meilleure traduction de cette nouvelle simplification du langage appelée « constructor property promotion », le titre décrit exactement ce changement. Les attributs de classe peuvent être directement et uniquement déclarés dans les paramètres du constructeur.

Voyons ça :

// PHP 7.x
class BlogPost
{
  protected string $title;
  protected TagList $tags;
  protected DateTimeInterface $createdAt
  public function __construct(string $title, TagList $tags, DateTimeInterface $createdAt) {
    $this->title = $title;
    $this->tags = $tags;
    $createdAt = $createdAt;
  }
}

// PHP 8.0
class BlogPost
{
  public function __construct(
    protected string $title,
    protected TagList $tags,
    protected DateTimeInterface $createdAt,
  ) {}
}

En réalité avec un IDE avancé comme PHPStorm, le volume de code écrit est plus ou moins le même. Mais il faut avouer que c’est plus lisible.

Virgule de fin dans les paramètres

Vous aurez peut-être remarqué une petite subtilité dans la déclaration du constructeur de la section précédente : le dernier paramètre est suivi d’une virgule… et ce n’est pas une typo !

En effet, les listes de paramètres acceptent désormais une virgule de fin, comme les arrays, à la déclaration et à l’appel. Aucun doute que j’ajouterai cette règle à ma configuration PHPCS.

Pour l’exemple, voyez au-dessus.

Nouvelles fonctions str_*

Déjà il y a 10 ans, l’une des premières versions de Shaarli contenait les fonctions startsWith() et endsWith() pour faire des vérifications sur les chaînes de caractères. Ces méthodes et leurs dérivées à base de strpos je les ai vues dans quasiment les projets sur lesquels j’ai pu travailler.

Une décennie plus tard, 3 nouvelles fonctions sont désormais disponibles dans la bibliothèque standard, et leur nom parle d’elles-mêmes : str_contains, str_starts_with() et str_ends_with().

Utilisation :

// All return true.
str_contains('All work and no play makes Jack a dull boy', 'Jack');
str_starts_with('All work and no play makes Jack a dull boy', 'All work');
str_ends_with('All work and no play makes Jack a dull boy', 'a dull boy');

Nouvelle interface Stringable

Stringable est une nouvelle interface de la bibliothèque standard. Pour l’implémenter il suffit d’implémenter une méthode __toString() qui sera appelée par défaut lors d’une conversion de l’objet.

En réalité, tout ça existe déjà, et il n’est pas nécessaire de spécifier explicitement implements Stringable, cela permet simplement de mieux gérer le typage.

En gros, cette nouvelle interface vous permet de faire ça :

class Greeting
{
  public function __toString(): string {
    return 'hi!';
  }
}

class NotGreeting
{
  public function __toString(): string {
    return 'come back later';
  }
}

class Greeter
{
  public function greet(Stringable $greeting): string {
    return 'Greeting: ' . $greeting;
  }
}

$greeter = new Greeter();
echo $greeter->greet(new NotGreeting()); // 'Greeting: come back later'
echo $greeter->greet(new Greeting()); // 'Greeting: hi!'

Pour faire cela en PHP 7.x, il n’aurait pas été possible de spécifier le type de la méthode greet() sans réunir NotGreeting et Greeting sous une même interface.

L’opérateur nullsafe

Une de mes features préférées de PHP 7.0 était l’opérateur null coalescent. Il n’y a rien de plus contre-productif que d’écrire 8 lignes de if pour vérifier que isset, array_key_exists, !== null ou autre instanceof.

PHP 8.0 me ravit donc en ajoutant l’opérateur nullsafe, qui permet de faire des appels de méthode sur un objet null.

// PHP 7.x
if (!$blogPost instanceof BlogPost || $blogPost->getCreatedAt() === null) {
  return null;
}
return $blogPost->getCreatedAt()->format('Y-m-d');

// PHP 8.0
return $blogPost?->getCreatedAt()?->format('Y-m-d');

Et si $blogPost ou $createdAt est null, on retourne tout simplement null, sans générer d’erreur fatale.

Lever des exceptions dans les expressions

Aller, tant qu’on est dans les petites améliorations qui améliorent la productivité et la lisibilité du code, il est désormais possible de lever des exceptions dans n’importe quelle expression. Je n’ai jamais bien compris pourquoi ce n’était pas possible - probablement des questions d’implémentation au niveau du code source de PHP - mais c’est réglé.

// PHP 7.x
$item = $collection->getItem($id);
if ($item === null) {
  throw new ItemNotFoundException();
}
return $item;

// PHP 8.0
return $collection->getItem($id) ?? throw new ItemNotFoundException();

match, le cousin du switch

J’utilise relativement rarement les switch {}, peut-être inconsciemment parce que c’est une expression assez verbeuse… switch, case:, break, et on répète. PHP 8.0 ajoute désormais l’expression match dont la syntaxe est similaire à celle existante en Java.

Concrètement, ça répond au même besoin que le switch, mais en plus lisible et compact avec une syntaxe array-like.

Voyons plutôt :

// PHP 7.x
switch ($locale) {
  case 'en_GB':
  case 'en_US':
    $language = Languages::ENGLISH;
    break;
  case 'de_DE':
    $language = Languages::GERMAN;
    break;
  default:
    $language = Languages::FRENCH;
}

// PHP 8.0
$language = match ($locale) {
  'en_GB', 'en_US' => Languages::ENGLISH,
  'de_DE' => Languages::GERMAN,
  default => Languages::FRENCH,
};

JIT (Just In Time) compiler

JIT compiler est une fonctionnalité de PHP 8.0 qui permet de compiler du code ré-utilisable directement pendant l’exécution, de la même façon qu’un cache pourrait opérer. Cela peut mener à de grandes amélioration de performances dans certains contextes.

C’est prometteur, mais c’est aussi une fonctionnalité assez complexe que je préfèrerait développer dans un article dédié. On en reparle ici bientôt !

Type de retour static

Je ne vais pas refaire le discours self vs static ici, mais sachez qu’il est désormais possible de définir le type de retour à static, en plus de self qui était déjà disponible.

class Entity {
  public function setProperty(int $property): static {
    $this->property = $property;

    return $this;
  }
}

Utilisation de ::class sur les objets

Il est maintenant possible d’appeler ::class directement sur les objets et pas uniquement sur les classes. Encore une petite amélioration qui simplifie la vie des développeurs.

// PHP 7.x
$className = get_class($myObject);
$className = MyClass::class;

// PHP 8.0
$className = $myObject::class;
$className = MyClass::class;

DateTime createFromInterface()

Vous avez déjà essayé de manipuler des DateTimeInterface, de créer des DateTimeImmutable et d’effectuer des opérations sur tout ça ? Non ? Eh bien vous avez de la chance, puisque l’implémentation en PHP 7.x est trouée, et qu’il y a de quoi y perdre quelques cheveux.

PHP 8.0 vient régler ça en ajoutant une méthode createFromInterface() aux classes DateTime et DateTimeImmutable, ce qui permet de convertir les objets de l’un à l’autre facilement.

Exemple, qui devrait vous faire saisir l’idée :

public function addMonth(DateTimeInterface $dateTime): DateTimeImmutable {
  $dateTime = DateTime::createFromInterface($dateTime);
  $dateTime->add(new DateInterval('P1M');

  return DateTimeImmutable::createFromInterface($dateTime);
}

Conclusion

Ça fait déjà pas mal de choses à se mettre sous la dent. Cet article n’a pas non plus vocation à être une release note complète.

Concernant les breaking changes, ils sont assez peu nombreux. Ça a toujours été une volonté forte de la part des développeurs de PHP - la contrepartie étant que cela peut freiner les évolutions.

Concrètement, la bascule en PHP 8.0 se fera facilement, si vous n’avez pas utilisé de syntaxes alambiquées. Mais attention, un certain nombre d’avertissements ont été convertis en erreur réelle. Il faudra donc peut être revoir votre gestion des erreurs.

Bon, on ne va pas se mentir, les montées de version sont souvent plus douloureuses au niveau de la gestion des dépendances que du langage en lui-même. Vous devriez évidemment attendre quelques semaines pour que les choses se stabilisent.

Encore quelques nouveautés pour conclure :

• Les méthodes privées (private) ne peuvent plus être déclarées comme final, ce qui était de toute façon un non sens.
• Il est désormais possible de catch une exception sans l’utiliser - et donc sans déclarer son nom de variable.

try {
} catch (SomeException) {
  // Do something not related to the exception variable
}

• La signature des méthodes abstraites dans les Trait doit désormais être strictement respectée dans les classes qui l’utilisent.
• Une implémentation de WeakMap a été ajoutée dans PHP 8.0. J’y reviendrais possiblement dans un article dédié.

Disclaimer : je propose ici une solution technique, et un workflow de publication, que j’ai adopté. La force des sites statiques étant leur grande souplesse, chaque partie détaillée dans cet article est interchangeable avec une autre solution de votre choix. Aussi, j’aurais pu utiliser Netlify qui est adapté aux sites statiques avec leur CDN, mais je ne souhaitais pas changer mon DNS racine.

Overview

Les chapitres suivants sont résumés dans ce diagramme :

Le moteur de blog : Hugo

Au coeur de notre workflow, il y a l’outil qui va nous permettre de construire notre site final, le blog. Pour produire un site dont le but est d’exposer du contenu accessible en lecture, les générateurs de sites statiques sont l’outil idéal, grâce à la souplesse qu’ils apportent.

À la différence d’un CMS (par exemple WordPress ou Drupal) qui traite dynamiquement chaque requête client via du code serveur et/ou une base de données, les générateurs de sites statiques produisent l’intégralité des fichiers HTML qui pourront être accessibles.

Par exemple, cet article que vous êtes en train de lire est un simple fichier HTML, qui a été généré à partir d’un fichier de contenu écrit en Markdown. De plus, le tag hugo est utilisé. Il existe donc un autre fichier HTML, qui contient la liste des articles associés à ce tag. L’important à retenir c’est qu’il n’y a pas de traitement serveur, ou de langage de programmation derrière, on sert simplement du contenu statique.

Les générateurs de sites statiques ne sont pas nouveaux, mais j’aime donner du contexte à ce que je publie et ne pas présumer du niveau du lecteur.

Dans ce qui nous intéresse ici, j’ai donc choisi le framework Hugo, écrit en Go, qui est probablement l’un des plus populaires au monde. Il en existe beaucoup d’autres, comme Jekyll (Ruby), Gatsby (JS), Zola (Rust), Pelican (Python), Sculpin (PHP), etc.

Finalement, peu importe la solution retenue, l’important c’est de trouver l’outil qui couvre les fonctionnalités que vous souhaitez intégrer à votre blog. Ici par exemple, la contrainte était principalement de gérer nativement le contenu multi-langues.

Je ne vais pas m’étendre sur l’installation et la configuration d’Hugo, pour cela la documentation est très complète et facile d’accès. L’essentiel est de pouvoir générer votre blog statique en une ligne de commande, ici simplement hugo.

La rédaction en local : Zettlr + git

Les générateurs de sites statiques offrent la plus grande flexibilité, puisque la seule chose nécessaire pour publier du contenu est d’écrire un fichier en Markdown.

Note : d’autres formats que Markdown sont supportés, mais c’est à mon avis le plus simple d’utilisation, tout en étant très complet.

Tous mes articles sont enregistrés dans le dossier /content/blog/ et correspondent au format suivant : YYYY-MM-DD-nom-d-article.lang.md. C’est simple, lisible et efficace.

Pour l’éditeur, évidemment tout est possible. Il est possible de tout rédiger sous ViM ou VSCode. Pour ma part, j’ai préféré me tourner vers des éditeurs spécialisés dans le Markdown. J’ai le sentiment que ma productivité est meilleure lorsque j’utilise un outil qui me procure une expérience utilisateur agréable et immersive.

J’ai commencé à écrire mes articles en local avec Typora avant de découvrir Zettlr qui est un bonheur à utiliser. Les deux outils sont puissants, mais ce dernier gère mieux la correction orthographique, la sauvegarde automatique, les métadonnées en en-tête, et le couple syntaxe markdown/formatage visuel.

Et bien sûr, tout le blog est placé dans un repository git. Plus précisément, dans un repo privé Github, avec le dossier /public ignoré. Vous allez comprendre pourquoi dans la suite de cet article lorsque l’on va attaquer l’automatisation du déploiement.

Il est privé parce que je fonctionne beaucoup avec des prises de note et des brouillons avant d’arriver à un article publié, et je ne souhaite pas que ce processus de création soit public. Pascal Martin décrit dans ce billet un fonctionnement dans lequel je me retrouve, même si mon cycle d’écriture est un peu plus court.

Dockerize me

Il est temps de mettre en ligne notre blog flambant neuf. Encore une fois, chacun a sa recette. Tout ce que l’on souhaite, c’est mettre nos fichiers HTML statiques derrière un serveur web.

Dans mon architecture, que je décrirai plus en détail à l’avenir, j’ai un ensemble de containers Docker qui tournent sur un serveur dédié, tous reliés à un reverse proxy nginx qui automatise la génération de certificats SSL Let’s Encrypt.

De fait, pour monter un nouveau service, tout ce que j’ai à faire c’est de créer un container Docker relié au réseau, généralement avec Docker Compose pour se simplifier la vie, et tout roule automatiquement.

Je ne crois pas qu’Hugo fournisse d’image officielle, mais une rapide requête dans mon moteur de recherche préféré m’a rapidement redirigé vers l’image de jojomi, qui en plus fourni une image annexe avec un nginx préconfiguré pour servir les fichiers statiques.

C’est la beauté de Docker, à partir de là, je n’ai plus rien à faire à part écrire un docker-compose.yml avec les variables qui vont bien :

version: '2'

services:
  hugo:
    image: jojomi/hugo:0.74.3
    volumes:
      - ./:/src
      - /data/blog/output/:/output
    environment:
      - HUGO_REFRESH_TIME=3600
      - HUGO_THEME=hello-friend-ng
      - HUGO_BASEURL=https://hoa.ro/
    restart: always
    network_mode: bridge

  web:
    image: jojomi/nginx-static
    volumes:
      - /data/blog/output:/var/www
    environment:
      - VIRTUAL_HOST=hoa.ro
      - VIRTUAL_PORT=80
      - LETSENCRYPT_HOST=hoa.ro
      - LETSENCRYPT_EMAIL=arthur@hoa.ro
    ports:
      - 80
    network_mode: bridge
    restart: always

On lance ensuite l’éternel

docker-compose up -d

Et vous y êtes. Ni plus, ni moins.

Maintenant, comment mettre à jour notre contenu ? Dans un premier temps, réfléchissons à le faire manuellement. C’est la première étape de l’automatisation.

Notre blog est relié à notre repository Github, donc il suffit de pull les dernières modifications, et de régénérer le contenu statique ; rappelez-vous que le dossier /public n’est pas synchronisé sur Git.

Une bonne habitude à prendre, c’est de toujours mettre dans un script ce type de commandes parce que, croyez-moi, on oublie rapidement. update.sh:

#!/bin/bash

git pull origin master
docker-compose exec -T hugo hugo -d /output

Même pas besoin de redémarrer le container !

Cette commande va exécuter hugo -d /output dans notre container Hugo et le tout ne prend que quelques secondes. Le dossier de sortie est modifié, car c’est ce qui a été spécifié dans notre Docker Compose.

Bien. On a un blog et un script de mise à jour. C’est rapide, il n’y a pas d’interruption de service. Mais on ne va pas s’amuser à se connecter en SSH chaque fois que l’on veut faire une mise à jour !

Continuous Deployment : Github’s webhooks

Des solutions de CD (Continuous Deployment), il y en a autant que de marques de lessive. Je ne vais pas les lister ni les analyser ici. En revanche, je sais exactement ce que je veux :

Quand un commit est effectué sur la branche master de mon repository sur Github, je veux exécuter le script update.sh de mon serveur dédié.

En bon développeur, au-delà de rechercher une solution adaptée, je cherche également la plus simple à mettre en place. Et un moyen simple de déclencher des évènements suite à un commit, ce sont les webhooks proposés par Github.

Un webhook c’est une requête HTTP POST qui est envoyée sur une URL de notre choix, chaque fois qu’un évènement se produit sur le repo. Ici, on ne s’intéresse qu’aux évènements de type push. Parfait, c’est tout ce dont on a besoin. Il n’y a plus qu’à traiter l’évènement sur notre serveur.

Encore une fois, je préfère aller au plus simple, et ça tombe bien puisque c’est ce que propose webhookd, un outil développé en Go :

A very simple webhook server launching shell scripts.

L’installation est simple, il suffit de suivre le README. Par contre, ce qui n’est pas vraiment expliqué, c’est comment utiliser ce logiciel comme un service systemd, afin de pérenniser notre installation.

Nous allons donc créer un service webhookd. Évidemment, je vous laisse adapter le tout à votre environnement. Ici, j’utilise un Debian et c’est root qui fait le café.

/etc/systemd/system/webhookd.service:

[Unit]
Description=WEBHOOKD

[Service]
ExecStart=/root/work/bin/webhookd
User=root
Group=root
EnvironmentFile=-/root/work/src/github.com/ncarlier/webhookd/etc/default/webhookd.env
EnvironmentFile=-/root/webhookd.env
Restart=always
Type=simple
RestartSec=30s

[Install]
WantedBy=multi-user.target

/root/webhookd.env:

WHD_SCRIPTS=/root/scripts  
WHD_LISTEN_ADDR=":<port>"

J’ai configuré l’installation pour glisser tous mes scripts dans /root/scripts, et j’ai configuré un port personnalisé sur lequel webhookd écoute.

J’ai ensuite créé un script intermédiaire, qui ajoute une vérification de token de sécurité, et qui lance notre fameux update.sh. webhookd gérant nativement les paramètres passés dans l’URL, le script n’est pas compliqué. /root/scripts/blog.sh:

#!/bin/bash  
  
if [[ $token != '<token>' ]]; then  
       echo "Access denied"  
       exit 1;  
fi  
  
cd /path/to/blog && ./update.sh

Et voilà, il ne reste qu’à créer un hook sur Github, et le tour est joué. Chaque push sur notre repo redéploie le blog statique avec les derniers changements.

NetlifyCMS

La mécanique est maintenant bien huilée, et je suis très satisfait de ce fonctionnement. Mes modifications apparaissent en production après un git push en quelques secondes.

Mais il reste un petit détail qui me chiffonne. Je l’ai dit plus haut, je fonctionne beaucoup à la prise de note ponctuelle, et aux brouillons sommaires avant de me lancer réellement dans la rédaction des articles. Et pour cela, devoir lancer un éditeur sur mon OS, une console, etc, ça peut être un peu lourd. C’est aussi pour cela que j’apprécie et utilise si facilement Shaarli.

En réponse à ce besoin, j’ai découvert NetlifyCMS. Il s’agit d’un outil open-source qui agit comme une UI de CMS, mais qui génère du contenu statique (des fichiers Markdown) et push le tout sur Git en un clic. Il fonctionne avec n’importe quel générateur de site statique, puisqu’il s’appuie uniquement sur un fichier de configuration TOML, et un import de fichier JS.

En clair, on met un fichier de configuration, un HTML avec une balise <script> dans notre repository, et on a une interface de rédaction d’article accessible dans le navigateur, qui publie automatiquement les modifications en production. Et la cerise sur le gâteau, il gère la rédaction multi-langues.

La documentation est assez bien fichue, donc je ne vais pas trop rentrer dans le détail de ma configuration. Voilà ce que ça donne avec Hugo, et un thème qui gère le multi-langues, static/admin/config.yml:

backend:
  name: github
  repo: arthurhoaro/<repo-name>
  branch: master
media_folder: "static/img"
public_folder: "/img"
i18n:
  structure: multiple_files
  locales: [en, fr]
  default_locale: en
collections:
  - name: "blog"
    label: "Blog"
    folder: "content/blog"
    create: true
    i18n: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - {label: "Title", name: "title", widget: "string", i18n: true}
      - {label: "Date", name: "date", widget: "datetime"}
      - {label: "Author", name: "author", widget: "hidden", default: "ArthurHoaro"}
      - {label: "Cover", name: "cover", widget: "hidden", default: ""}
      - {label: "Tags", name: "tags", widget: "list", i18n: true}
      - {label: "keywords", name: "keywords", widget: "list", i18n: true}
      - {label: "Description", name: "description", "string", i18n: true}
      - {label: "showFullContent", name: "showFullContent", widget: "hidden", default: true}
      - {label: "draft", name: "draft", widget: "boolean", default: true}
      - {label: "Body", name: "body", widget: "markdown", i18n: true}

Prévisualisation des brouillons

Il reste un petit détail à peaufiner. Pour la phase de relecture, je préfère le faire sur le rendu final plutôt que dans l’éditeur Markdown.

Évidemment, il est possible de faire tourner le serveur en local avec hugo server -D -F : -D pour compiler les brouillons, -F pour compiler les fichiers datés dans le futur. Sauf que ça n’est pas du tout pratique avec la publication via NetlifyCMS.

Encore une fois, j’ai opté pour une solution simple : monter une instance développement sur laquelle les brouillons sont accessibles. L’instance de test est protégée par une authentification basic HTTP.

Je vous invite à rependre les autres sections, mais pour résumer rapidement : nouvelle image Docker, nouveau script update.sh en compilant les brouillons, nouveau webhook Github, nouveau script webhookd et on est bon. Une fois qu’on a tout fait en production, cette étape est réglée en 5 minutes.

Conclusion

Cet article est un peu plus long que ce que j’avais anticipé. Je pense que j’ai mis plus de temps à l’écrire qu’à le mettre en place le workflow à l’origine.

Toujours est-il que vous avez toutes les clés en main pour mettre en place un blog statique, avec l’outillage de rédaction et le déploiement automatique.

J’ai décrit ici mon workflow, et j’ai tenté de faire en sorte que chaque section soit modulable, pour qu’elles soient adaptables à vos besoins et usages.

À vous de jouer ! Et n’hésitez pas à me partager vos améliorations.

UPDATE 2020-11-29: le générateur a été mis à jour avec la nouvelle version du PDF (déplacement à 20km)

Un second confinement est en place depuis le 30 novembre en France métropolitaine afin de lutter contre l’épidémie de COVID-19. À ce titre, tout déplacement doit être justifié au moyen d’une attestation de déplacement dérogatoire. Si vous êtes français, je ne vous apprends rien, mais je préfère toujours donner le contexte.

Bref, pour obtenir cette attestation, vous pouvez soit l’imprimer, soit la recopier sur papier libre, soit - et c’est ce qui nous intéresse - utiliser le générateur de PDF mis à disposition par l’incubateur du ministère de l’Intérieur. Il est disponible ici. Sauf qu’à l’heure où j’écris ces lignes, il a plusieurs défauts qui rendent son utilisation vraiment fastidieuse :

• il faut remplir ses informations personnelles à chaque génération et l’autocomplétion du navigateur est désactivée
• la description des motifs alambiquée, il m’a fallu quelques minutes pour comprendre quelle case cocher pour aller faire des courses
• l’heure n’est pas préremplie

Cela dit, il est appréciable que le gouvernement ait mis à disposition le code source, puisque j’ai pu régler tous ces problèmes, Docker-iser tout ça et mettre en ligne une version modifiée en à peine plus d’une heure. Code source

C’est accessible ici : https://attestation.hoa.ro Vous pouvez l’utiliser si vous le souhaitez.

Aucune information n’est stockée sur le serveur. Les valeurs des champs renseignés sont stockées dans le local storage du navigateur, et pour le reste je n’ai pas modifié le fonctionnement : toute la tambouille est faite côté client.

Détail des modifications :

• les champs renseignés sont stockés dans le local storage, donc il suffit de les renseigner une seule fois
• ajout d’un build Docker afin de le faire tourner facilement sur mon serveur
• pour le moment, le serveur tourne en mode dev, parce qu’il y a des choses que je ne veux pas générer en HTML statique (l’heure actuelle par exemple)
• ajout d’un deuxième bouton de validation en haut de page
• ultra-simplification des motifs de déplacement, si vous avez besoin du détail, allez sur le site du gouvernement

Aujourd’hui, je ressens de nouveau l’envie d’écrire sur les sujets qui me passionnent, en particulier le développement web. Nous y voilà donc, et il va me falloir un peu de pratique pour reprendre cette activité qui me paraissait alors plus naturelle.

Pour ce blog, j’ai pris le parti d’utiliser Hugo qui est un excellent outil de site statique, écrit en Go, dans lequel je peux rédiger en Markdown.

J’ai également décidé d’écrire mes billets en français et en anglais. Il me parait important d’écrire en français parce que c’est ma langue maternelle, et que je souhaite sincérement que la communauté française de développeurs et autres curieux perdure. Mais aussi en anglais puisqu’il s’agit d’un langage international, en particulier dans ce domaine, touchant le plus grand nombre. De plus, d’un point de vue personnel, j’envisage dans un futur proche de m’installer dans un pays anglophone.

Je ne vais pas m’étendre davantage dans ce billet d’introduction. Si vous voulez en savoir plus sur moi, je vous invite à visiter à visiter la page « À propos », ou mes différents contacts disponibles sur la page d’accueil.

J’espère que ce que je publierai vous intéressera, et d’ici là n’hésiter pas à ajouter le flux RSS à vos aggrégateurs, ou celui de mon Shaarli sur lequel je relaierai les billets.