Aller au contenu

TLS et domaines Mis à jour le 2026-05-27

Let's Encrypt avec Node.js

Utiliser l'add-on Let's Encrypt avec une application Node.js — lire les certificats depuis le code, configurer les hooks de renouvellement et suivre le motif recommandé avec répartiteur.

L’add-on Let’s Encrypt automatise l’émission et le renouvellement de certificats pour la plupart des piles applicatives — il provisionne le certificat, configure la terminaison TLS en façade et recharge le service. Node.js est l’exception. Le processus Node.js étant lui-même le serveur qui termine TLS, l’add-on ne peut pas lier le certificat à votre place — il se contente d’écrire les fichiers émis sur disque.

Deux motifs raisonnables pour Node.js avec Let’s Encrypt :

  1. Lire les fichiers de certificat directement depuis votre application Node.js. Documenté ci-dessous.
  2. Placer un répartiteur devant Node.js et installer l’add-on sur le répartiteur. Recommandé en production, surtout si vous voulez aussi la mise à l’échelle horizontale. Le répartiteur termine TLS et transmet en HTTP non chiffré vers Node.js — l’add-on automatise le renouvellement et le rechargement sur le répartiteur comme pour n’importe quelle pile.

Emplacement des fichiers de certificat

Après installation de l’add-on Let’s Encrypt sur un nœud Node.js, les certificats sont écrits à :

  • /var/lib/stackharbor/keys/privkey.pem
  • /var/lib/stackharbor/keys/fullchain.pem
  • /var/lib/stackharbor/keys/ca.cer

Le processus Node.js doit pouvoir lire ces fichiers et écouter sur le port 443 (root ou capability requise — sudo au lancement est l’approche habituelle).

Nouvelle application — serveur HTTPS minimal

Remplacez le server.js par défaut dans /home/stackharbor/ROOT par :

const https = require('node:https');
const fs = require('node:fs');

const options = {
  key: fs.readFileSync('/var/lib/stackharbor/keys/privkey.pem'),
  cert: fs.readFileSync('/var/lib/stackharbor/keys/fullchain.pem')
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('hello world\n');
}).listen(443);

console.log('Serveur HTTPS à l\'écoute sur https://localhost:443/');

Démarrez-le via Web SSH (le terminal dans le navigateur) avec le gestionnaire de processus de votre choix. Exemple avec forever :

cd /home/stackharbor/ROOT
sudo forever start server.js

Ou sans gestionnaire de processus :

sudo node server.js

Application existante — ajouter HTTPS

Pour une application existante, enveloppez les mêmes options key / cert autour de votre appel à createServer. Le motif est le même : importer les fichiers de certificat au démarrage, les passer à https.createServer, écouter sur 443.

Si vous servez aussi HTTP en clair (pour les challenges ACME ou les redirections), écoutez aussi sur 80.

Renouvellement — hook de redémarrage

Les certificats Let’s Encrypt sont valides 90 jours. L’add-on les renouvelle automatiquement 30 jours avant expiration, mais Node.js ne prend pas en compte le nouveau certificat tant que le processus n’a pas redémarré (Node lit les fichiers une seule fois au démarrage).

Branchez un hook de renouvellement pour que l’add-on recharge votre processus Node.js après chaque renouvellement :

  1. Créez le fichier /var/lib/stackharbor/keys/letsencrypt/settings-custom (créez le dossier letsencrypt s’il n’existe pas).
  2. Ajoutez une ligne deployHook indiquant la commande à exécuter après renouvellement. Exemple pour forever :
deployHook=sudo forever restart /home/stackharbor/ROOT/server.js

Alternative — pointer le hook vers un script shell :

deployHook=/path/to/reload.sh

Assurez-vous que le script est exécutable (chmod +x reload.sh). Exemple :

#!/bin/bash
sudo forever restart /home/stackharbor/ROOT/server.js

Vous pouvez aussi déclencher un renouvellement manuel depuis le menu Add-Ons sur le nœud Node.js pour tester le hook sans attendre l’expiration.

Motif recommandé en production

Au-delà d’une démo mono-nœud, placez un répartiteur (NGINX ou HAProxy) devant le nœud Node.js, installez l’add-on Let’s Encrypt sur le répartiteur, et laissez-le terminer TLS. Le répartiteur se recharge automatiquement à chaque renouvellement — Node.js ne voit jamais les fichiers de certificat. La mise à l’échelle horizontale devient triviale.

Voir aussi