Faire tourner Docusaurus avec Docker

Simplifiez votre workflow Docusaurus avec une configuration propre et reproductible. Dans ce guide mis à jour, vous allez apprendre à maintenir un blog Docusaurus avec une seule image Docker, les DevContainers de VSCode et un workflow qui rend à la fois les builds de production et l'écriture quotidienne rapides et fiables.

Il y a dix-huit mois, j'ai publié Encapsuler un site Docusaurus entier dans une image Docker mais, depuis, j'ai affiné l'approche, surtout autour de la séparation propre des environnements de production et de développement (voir Une seule image Docker pour la production et les Devcontainers - la méthode propre).

Avec ce setup :

• Vous lancez make build une seule fois pour créer une image Docker de base.
• Vous démarrez votre environnement d'édition avec make devcontainer.
• VSCode construit et ouvre automatiquement un container isolé avec tout de configuré.

Si Docusaurus est tout nouveau pour vous, commencez par Exécuter Docusaurus avec Docker ; et une fois le site construit, GitHub - Utiliser les Actions pour déployer ce blog s'occupe de le publier.

Voyons le workflow complet.

Voici où on va : make build une fois, make up, et le blog tourne déjà.

Quelques commandes plus bas et vous y serez aussi.

Récupérer un blog Docusaurus​

Si vous avez déjà un blog Docusaurus, sautez simplement ce chapitre. Pour la démonstration, nous allons utiliser le blog d'un ami, Docux, qui publie des composants et plugins Docusaurus très utiles.

Récupérez une copie de son blog en lançant les commandes ci-dessous :

$ cd /tmp && git clone git@github.com:Juniors017/docux-blog.git && cd docux-blog▋

Créer l'image Docker de base​

Si vous débutez avec Docusaurus, vous vous demandez peut-être : comment faire tourner le blog en local, tout simplement ?. Réponse rapide : en lançant une image Docker autonome, et c'est ce que nous allons voir dans ce chapitre.

Ouvrez d'abord VSCode en lançant code . :

$ code .▋

Vous devriez maintenant voir la structure du projet dans votre éditeur.

Créer les fichiers requis​

À la racine du projet, créez les fichiers suivants :

Construire et lancer l'image de production​

Une fois les fichiers en place, lancez make dans une console et vous obtiendrez un écran comme celui-ci :

Si make n'est pas encore installé sur votre machine, vous obtiendrez une erreur : installez donc d'abord make :

$ sudo apt-get update && sudo apt-get install make▋

Nous devons maintenant lancer deux commandes. La première va créer une image Docker pour la production, c'est-à-dire où tout est inclus dans l'image.

$ TARGET=production make build▋

Vous obtiendrez un écran comme celui-ci et il faudra patienter environ 80 secondes le temps que l'image soit construite.

Cela fait, lancez la seconde commande pour créer une instance en cours d'exécution de l'image, c'est-à-dire un container :

$ TARGET=production make up▋

Ce sera très rapide et vous verrez dans la console un message indiquant Open the PROD blog (https://localhost).

Et vous savez quoi ? C'est déjà fait : rendez-vous sur https://localhost et laissez-vous surprendre — le blog tourne, exactement le résultat annoncé en haut de cet article.

Utiliser les DevContainers pour le développement​

Construire l'image de production, c'est bien et utile si vous voulez la publier sur Docker Hub, mais il nous faut aussi un workflow d'édition confortable. Avec les DevContainers de VS Code, nous obtenons un environnement totalement isolé, taillé pour Docusaurus.

Lancez d'abord make build (notez qu'ici, nous ne précisons pas TARGET=production). Ce sera extrêmement rapide puisque tout a déjà été créé avant.

Ensuite, lancez make devcontainer pour ouvrir VSCode et... rien ne se passe pour l'instant : c'est normal, nous devons créer des fichiers supplémentaires.

Créer le dossier .devcontainer​

Nous devons créer un nouveau dossier .devcontainer avec quelques fichiers :

Comme nous avons deux scripts bash, nous devons les rendre exécutables. Lancez cette commande dans un terminal :

$ chmod +x .devcontainer/bootstrap.sh .devcontainer/bash_helpers.sh▋

Il nous faut maintenant ouvrir le devcontainer, alors lancez :

$ make build && make devcontainer▋

Une fois dans VSCode, appuyez sur F1 pour ouvrir la Command Palette et lancez Dev Containers: Rebuild Without Cache and Reopen in Container.

Cliquez donc pour lancer l'action Dev Containers: Rebuild and Reopen in Container. Si vous regardez le terminal (depuis VSCode), vous verrez beaucoup de messages comme ceux ci-dessous :

À un moment donné, vous verrez ceci :

Cela signifie que Docusaurus est prêt à servir votre contenu.

Rendez-vous sur https://localhost:3000 et tadaaa.

Jouons un peu. Ouvrez le dossier blog et créez un nouveau fichier appelé index.md :

Sauvegardez et, oh ?, votre navigateur reflète immédiatement le changement (le hot reload est bien activé) :

Utiliser le terminal depuis le devcontainer​

Un autre point vraiment sympa : l'utilisation du Terminal, toujours dans VSCode.

En cas de besoin, appuyez sur CTRL+ù pour ouvrir le Terminal et repérez le bouton + en haut à droite de cette fenêtre. Cliquez sur le + pour en créer un nouveau :

Vous avez vu ? Vous obtenez un écran d'accueil avec quelques actions à lancer. Par exemple, pour mettre à jour Docusaurus vers la dernière version, il suffit de lancer upgrade et c'est tout.

Pourrait-on faire plus simple ?

Quels sont les avantages d'une telle approche ?​

Ils sont si nombreux... Commençons par celui-ci : sur mon host, je n'ai que Docker et rien d'autre. Je n'ai pas besoin d'installer Node comme l'exige Docusaurus, ni aucune dépendance Linux.

Je peux aussi construire mon blog comme une image autonome. Regardez mon image Docker cavo789/blog sur https://hub.docker.com/r/cavo789/blog. Si vous voulez la faire tourner sur votre propre machine, il suffit de lancer docker pull cavo789/blog && docker run -d -p 443:443 --name blog cavo789/blog puis d'aller sur https://localhost et c'est tout.

Avec un Devcontainer comme illustré dans cet article, vous pouvez aussi affiner votre environnement, c'est-à-dire indiquer quelle extension doit être installée dans VSCode et comment elle doit être configurée. Vous pouvez également définir le look&feel de l'éditeur (la police, la taille, la couleur, le template, ...).

Comme tout est isolé, vous pouvez jeter le container et le recréer sans douleur.

Vous travaillez en équipe ? Le devcontainer est alors la voie à suivre puisque tout le monde aura exactement le même environnement.

Utiliser LanguageTool dans VSCode​

Voyons l'un des nombreux avantages : plutôt que de simplement utiliser VSCode pour écrire nos articles, utilisons LanguageTool qui fournit une vérification de base de la grammaire et de l'orthographe de vos articles.

Et vous savez quoi ? Vous l'avez déjà. Regardez votre fichier .devcontainer/compose.yaml. Vous verrez un service appelé languagetool basé sur une image Docker appelée erikvl87/languagetool. Et maintenant, regardez votre fichier .devcontainer/devcontainer.json. Cherchez languageToolLinter et vous verrez une URL locale (basée sur une IP) ; c'est celle exposée par le service. Cherchez ensuite l'extension davidlday.languagetool-linter, c'est elle qui fait la magie.

Voici un exemple de LanguageTool à l'œuvre :

Bien sûr, la phrase correcte devrait être This example illustrates LanguageTool in action.

Code Spell Checker​

Voici un autre exemple, une erreur qu'un francophone peut faire par inadvertance :

Ici, l'extension utilisée est Code Spell Checker de streetsidesoftware.

Markdown lint​

Et peut-être que, pendant que vous écrivez votre contenu Markdown, VSCode vous affichera des erreurs en orange comme MD047/single-training-newline pour vous dire que vous avez oublié d'ajouter une ligne vide tout en bas du fichier.

Ces avertissements viennent de Markdownlint, une autre extension déjà installée dans le devcontainer.