Encapsuler un site Docusaurus complet dans une image Docker

Commencé le 2 novembre 2023, cet article est déjà le centième que je publie sur ce blog. Pour marquer l'occasion, je voulais faire quelque chose d'un peu spécial en l'honneur du blog. Quoi de mieux qu'une version 100% Docker, c'est-à-dire sous la forme d'une image Docker téléchargeable que vous pouvez lancer avec une seule ligne de commande.

Une seule commande pour télécharger le blog et le faire tourner sur votre machine (Linux, Mac ou Windows) avec un site parfaitement fonctionnel ; sympa, non ?

Et comme d'habitude, vous trouverez ci-dessous toutes les informations nécessaires pour faire de même avec votre propre installation Docusaurus.

Voyons maintenant comment faire la même chose pour votre propre instance Docusaurus. Mesdames et messieurs, suivez le guide...

Résultat​

Cette unique commande docker run de l'AlertBox ci-dessus vous donne ceci, entièrement hors ligne :

La suite de cet article construit l'image qui produit ce résultat : un Dockerfile multi-stage qui transforme n'importe quel site Docusaurus en une seule image autonome de ~87 Mo.

Créer un blog bidon si besoin​

Si vous avez déjà une installation Docusaurus sur votre ordinateur, sautez ce chapitre. Sinon, Exécuter Docusaurus avec Docker couvre la configuration de développement qui précède celle-ci.

Dans cette partie, je suppose que vous n'avez pas encore d'installation Docusaurus. Nous allons donc créer un site bidon avec quelques articles de blog très basiques.

Ouvrez une console et lancez les commandes suivantes : mkdir /tmp/docusaurus && cd $_.

Vous êtes maintenant dans le dossier /tmp/docusaurus.

Copiez/collez dans la console les instructions ci-dessous, parenthèses incluses. Cela va créer un sous-dossier appelé blog avec trois fichiers Markdown dedans, nos trois faux articles.

(
  $ mkdir -p blog && cd $_
  $ echo '---' > 2024-04-26-welcome-world.md
  $ echo 'title: Hello World!' >> 2024-04-26-welcome-world.md
  $ echo '---' >> 2024-04-26-welcome-world.md
  $ echo 'Hello world! Proud to be here!!!' >> 2024-04-26-welcome-world.md
  $ echo '---' > 2024-04-27-my-first-post.md
  $ echo 'title: My first blog post' >> 2024-04-27-my-first-post.md
  $ echo '---' >> 2024-04-27-my-first-post.md
  $ echo 'My first blog post' >> 2024-04-27-my-first-post.md
  $ echo '' >> 2024-04-27-my-first-post.md
  $ echo '![Unsplash random](https://source.unsplash.com/random?dinosaure)' >> 2024-04-27-my-first-post.md
  $ echo '---' > 2024-04-28-my-second-post.md
  $ echo 'title: My second blog post' >> 2024-04-28-my-second-post.md
  $ echo '---' >> 2024-04-28-my-second-post.md
  $ echo 'My second blog post' >> 2024-04-28-my-second-post.md
  $ echo '' >> 2024-04-28-my-second-post.md
  $ echo '![Unsplash random](https://source.unsplash.com/random?dinosaure)' >> 2024-04-28-my-second-post.md
)
▋

Voilà, nous avons maintenant un blog bidon.

Préparer notre installation Docusaurus pour Docker​

Si vous avez sauté le chapitre précédent parce que vous aviez déjà une instance Docusaurus, placez-vous dedans (cd <your_docusaurus_folder>).

Nous allons devoir créer quelques fichiers pour Docker.

Lancez votre éditeur préféré et ouvrez le dossier ; de mon côté, j'utilise Visual Studio Code, donc je lance simplement code . dans ma console Linux.

Il nous faut créer quelques fichiers...

Créer un fichier Dockerfile​

Créez un fichier appelé Dockerfile avec ce contenu :

# syntax=docker/dockerfile:1?

# Inspired by https://docusaurus.community/knowledge/deployment/docker/?package-managers=yarn

# Stage 1: Base image.

FROM node:22-alpine AS base?

# Disable color output from yarn to make logs easier to read.
ENV FORCE_COLOR=0?

# Enable corepack.
RUN corepack enable?

# --------------------------------------------------------------------

# Stage 2: Production build mode.

FROM base AS building_production?

# Install the latest version of Docusaurus
RUN npx create-docusaurus@latest /opt/docusaurus/ classic --javascript \?
  # Uncomment the line below to remove dummy files like dummy blog, docs, src, ...
  # && rm -rf /opt/docusaurus/blog /opt/docusaurus/docs /opt/docusaurus/src\
  && chown -R node:node /opt/docusaurus/?

# Set the working directory to `/opt/docusaurus`.
WORKDIR /opt/docusaurus

# We need our package.json / yarn.lock file before running yarn install
COPY package.json yarn.lock ./?

# Install dependencies with `--immutable` to ensure reproducibility.
RUN yarn install --immutable?

# Copy over the source code.
COPY . /opt/docusaurus/?

# Build the static site (generated files will be created in /opt/docusaurus/build)
RUN yarn build?

# --------------------------------------------------------------------

# Stage 3: Serve with nginx

FROM nginx:stable-alpine3.19-perl AS production?

# Copy the Docusaurus build output.
COPY --from=building_production /opt/docusaurus/build /usr/share/nginx/html?

WORKDIR /usr/share/nginx/html

Ce fichier est un Dockerfile multi-stage. Les objectifs principaux sont d'avoir un meilleur système de cache des layers et une image finale plus petite en taille. Un fichier multi-stage est aussi très pratique pour pouvoir construire plusieurs images, par exemple une de développement et une de production.

Comme vous le voyez, nous utilisons trois stages (un stage commence par la clause FROM).

Notre but dans cet article est de créer une image Docker finale contenant une version statique de notre installation Docusaurus. Nous voulons une image contenant un serveur web et notre site.

Avant de pouvoir faire ça, il nous faut :

1. Utiliser une image node puisque Docusaurus est une application NodeJS. Nous utiliserons node:21-alpine comme image de base.
2. Ensuite, il faut installer docusaurus et lancer yarn pour installer les dépendances. Cela fait, nous copierons tous les fichiers de notre dossier courant dans l'image Docker. Une fois copiés, il faut builder notre site et convertir les fichiers Markdown en pages HTML et, enfin,
3. Il nous faut un serveur web comme Apache, Caddy ou nginx (Caddy donnera l'image la plus petite mais configurer le SSL avec Docker reste assez compliqué).

Voilà nos trois stages.

Le stage 1 s'appelle base. Dans ce stage, on ne fait presque rien : télécharger une version alpine de node et initialiser quelques variables. Cette étape pourra, à l'avenir, aussi servir à un stage development mais, dans cet article, concentrons-nous sur celui de production.

FROM node:21-alpine AS base?

# Disable color output from yarn to make logs easier to read.
ENV FORCE_COLOR=0?

# Enable corepack.
RUN corepack enable?

Dans le stage 2, appelé building_production, nous étendons le stage base.

Comme vous le voyez ci-dessous, nous allons installer Docusaurus et ses dépendances.

Ensuite, nous copierons les fichiers de notre dossier courant dans l'image en cours de création et, enfin, nous générerons (builderons) les pages web statiques (HTML, CSS, JavaScript et images).

À la fin de ce stage, nous obtiendrons une version statique de notre site Docusaurus dans le dossier /opt/docusaurus/build.

FROM base AS building_production?

# Install the latest version of Docusaurus
RUN npx create-docusaurus@latest /opt/docusaurus/ classic --javascript \?
  # Uncomment the line below to remove dummy files like dummy blog, docs, src ...
  # && rm -rf /opt/docusaurus/blog /opt/docusaurus/docs /opt/docusaurus/src \
  && chown -R node:node /opt/docusaurus/?

# Set the working directory to `/opt/docusaurus`.
WORKDIR /opt/docusaurus

# We need our package.json / yarn.lock file before running yarn install
COPY package.json yarn.lock ./?

# Install dependencies with `--immutable` to ensure reproducibility.
RUN yarn install --immutable?

# Copy over the source code.
COPY . /opt/docusaurus/?

# Build the static site (generated files will be created in /opt/docusaurus/build)
RUN yarn build

Ce qui est important à noter ici, c'est notre répertoire de travail : /opt/docusaurus/. Notre site statique a été copié dans ce dossier, donc le résultat de la dernière instruction du deuxième stage (yarn build) va créer un sous-dossier build dans /opt/docusaurus/.

À la fin de ce stage, nous avons notre site statique mais pas encore de serveur web.

Dans le stage 3, nous allons utiliser nginx.

FROM nginx:stable-alpine3.19-perl AS production?

# Copy the Docusaurus build output.
COPY --from=building_production /opt/docusaurus/build /usr/share/nginx/html?

WORKDIR /usr/share/nginx/html?

Comme vous le voyez, ce stage est très basique. On utilise juste nginx, on copie le site statique créé plus tôt dans son dossier web par défaut et c'est tout.

Créer un fichier .dockerignore​

Le deuxième fichier à créer doit s'appeler .dockerignore et contenir ceci :

build/?
node_modules/?
.git/?

.dockerignore
.gitignore
.markdownlint_ignore
.markdownlint.json
*.log?
compose.yaml
Dockerfile
LICENSE
makefile
README.md

Le fichier .dockerignore est là pour demander à Docker de ne pas tout copier dans votre image finale lors de l'exécution de l'instruction COPY . /opt/docusaurus/ présente dans le Dockerfile.

En effet, dans notre image finale, nous n'avons pas besoin par exemple des dossiers build/ ou node_modules/ puisqu'ils seront créés pendant le build de l'image. Nous n'avons pas besoin de notre dossier .git/ (s'il existe) non plus, ni des fichiers temporaires ou nécessaires uniquement au build.

Le fichier .dockerignore sert donc à garder une image plus petite et à éviter de copier des fichiers sensibles (ceux contenant des secrets ou des éléments de configuration) dans l'image finale.

Petit résumé​

Si vous avez suivi la création du dossier temporaire décrite plus haut, vous devriez avoir la situation suivante : deux fichiers dans le dossier /tmp/docusaurus et trois fichiers Markdown dans le sous-répertoire blog.

$ ls -alhR
drwxr-xr-x  3 root root 4.0K Apr 28 11:02 .
drwxrwxrwt 25 root root  12K Apr 28 10:44 ..
-rw-r--r--  1 root root  155 Apr 27 09:47 .dockerignore
-rw-r--r--  1 root root 1.2K Apr 28 10:45 Dockerfile
drwxr-xr-x  2 root root 4.0K Apr 28 11:02 blog
.
$ ls -alh ./blog:
.
drwxr-xr-x 2 root root 4.0K Apr 28 11:02 .
drwxr-xr-x 3 root root 4.0K Apr 28 11:02 ..
-rw-r--r-- 1 root root   61 Apr 28 11:02 2024-04-26-welcome-world.md
-rw-r--r-- 1 root root  119 Apr 28 11:02 2024-04-27-my-first-post.md
-rw-r--r-- 1 root root  121 Apr 28 11:02 2024-04-28-my-second-post.md
▋

Builder notre image Docker​

Notre objectif était de créer une image Docker contenant notre site Docusaurus.

Quand on crée une image Docker, il faut lui donner un nom.

Toujours dans votre console, lancez la commande suivante :

$ docker build --tag johndoe/blog --target production .▋

Le . final dans l'instruction ci-dessus signifie dossier courant ; /tmp/docusaurus dans mon cas.

La commande docker build prendra une ou deux minutes selon la vitesse de votre connexion réseau et de votre ordinateur. Une fois exécutée avec succès, vous aurez une nouvelle image Docker sur votre machine. Vous pouvez la retrouver en lançant docker image list pour obtenir la liste des images locales.

Et l'utiliser​

Maintenant que notre image est créée, on peut faire plusieurs choses : la lancer simplement pour obtenir une version hors ligne de notre site Docusaurus, jouer avec un container et démarrer une session shell interactive ou, bien sûr, la publier sur Docker Hub.

Lancer l'image, c'est-à-dire créer un container et faire tourner le site​

Pour ça, lancez simplement la commande suivante :

$ docker run -d --publish 80:80 --name blog johndoe/blog▋

Très vite, vous obtiendrez un très long ID en résultat, du genre cae6989bee2a2339a4c0116be2b86ee3dae0b46d47a6c53dcb6e50098726c0b1. Ignorez-le pour le moment, ça veut juste dire que votre container a été créé avec succès.

Maintenant, lancez votre navigateur et rendez-vous sur http://localhost:80 — c'est la page d'accueil et le blog montrés en haut de cet article.

Comme dit plus haut, le site tournera sur votre ordinateur, donc hors ligne. Vous pouvez vous déconnecter d'Internet, tout tourne en RAM ; sur votre machine.

Si vous êtes curieux, lancez docker ps (ou docker container list, qui est un synonyme) pour voir la liste des containers. Vous verrez le vôtre.

En lançant docker container stop blog (blog est le nom défini dans le docker run utilisé plus haut dans ce chapitre), on peut arrêter le blog. Retournez dans votre navigateur, allez sur http://localhost:80 et vous verrez : le site n'est plus actif. Lancez docker container start blog pour le réactiver.

Démarrer une session shell interactive​

Si vous voulez démarrer un shell interactif dans votre image, lancez simplement docker run -it johndoe/blog /bin/sh. Vous serez alors à l'intérieur du container et vous pourrez inspecter les fichiers, par exemple.

Attention à bien comprendre la notion de container : votre site tourne dans un container et vous venez d'en démarrer un second. Pour le prouver, lancez rm -rf blog pour tuer le blog dans votre container shell, retournez dans le navigateur, rafraîchissez la page : ça fonctionne toujours.

Tapez exit pour quitter le shell et revenir à votre console. Relancez docker run -it johndoe/blog /bin/sh et vérifiez si le dossier blog supprimé est là ou pas : il est là.

Un container est quelque chose qui est recréé à chaque fois, donc tout ce qui est fait dans un container (quand il n'y a pas de volumes montés comme celui utilisé ici) reste juste en RAM.

La pousser sur Docker​

Avant de pouvoir publier votre image sur Docker Hub, assurez-vous d'abord d'être connecté.

Lancez docker login dans votre ligne de commande et connectez-vous avec un compte valide. Si vous étiez déjà authentifié, vous verrez Authenticating with existing credentials...

Maintenant, poussez votre image en lançant docker image push suivi du nom de votre image ; dans mon cas, ce sera cavo789/blog puisque je suis connecté en tant que cavo789.

La récupérer depuis Docker Hub​

La boucle est bouclée... Vous pouvez dire à vos amis et collègues qu'ils peuvent désormais utiliser votre image en lançant simplement la commande docker pull <your_image> && docker run -d -p 80:80 --name blog <your_image> comme je l'indiquais en préface de cet article.

Amusez-vous bien !