Docker: Node.js

Comment utiliser et déployer une application Node.js avec Docker

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose une solution Docker cloud CaaS (Containers as a Service) prête à l'emploi qui offre de nombreux avantages, notamment :

Déployez facilement vos conteneurs en production avec un simple docker-compose up.

Nom de domaine personnalisable sécurisé en HTTPS (par exemple, https://api.votre-entreprise.com, https://www.votre-entreprise.com, https://backoffice.votre-entreprise.com).

Performance optimale et sécurité renforcée grâce à une VM privée et dédiée.

Mises à jour simplifiées en un clic.

Gagnez du temps et simplifiez-vous la vie : il suffit de 5 minutes pour essayer la solution Docker CaaS cloud hosting de Stackhero et déployer vos conteneurs en production !

Ce guide vous offre une base solide pour développer une application Node.js et la déployer en production rapidement et facilement.

Aucune connaissance préalable de Docker n'est nécessaire. Tout est prêt pour garantir une expérience fluide, il suffit d'avoir Docker installé sur votre ordinateur.

Cette documentation s'adresse aussi bien aux débutants qu'aux utilisateurs expérimentés souhaitant déployer une application Node.js avec des technologies modernes et scalables, sans complexité inutile.

Les points forts de cette solution incluent :

💪 Mise en place facile avec un minimum d'efforts
🐳 Utilisation de Docker pour les environnements de développement et de production
🔄 Rechargement automatique de Node.js lors des modifications du code grâce à nodemon
🚀 Déploiement en production en une seule commande
🔒 Gestion des certificats TLS pour un chiffrement HTTPS sécurisé
🚧 Prise en charge des plateformes de staging et de préproduction
🧱 Architecture modulaire et évolutive

Premiers pas

Si Docker n'est pas encore installé sur votre ordinateur, vous pouvez le télécharger depuis le site officiel de Docker. Pour vérifier que Docker fonctionne correctement, ouvrez un terminal et exécutez docker version. Vous devriez voir les informations de version sans erreur.

Après avoir installé Docker, clonez le dépôt boilerplate suivant :

git clone https://github.com/stackhero-io/nodejsWithDockerGettingStarted/
cd nodejsWithDockerGettingStarted

Ensuite, lancez la plateforme de développement avec la commande make development-start ou affichez toutes les commandes disponibles avec make help.

Plateforme de développement

Pour démarrer la plateforme de développement, exécutez :

make development-start

Cette commande construit l'image Docker, la lance et exécute le script dev défini dans my-app/package.json (équivalent à npm run dev).

Dans cet exemple, une API REST simple utilisant Express est créée. Vous pouvez consulter l'API en accédant à http://localhost:5000. La page doit afficher "Hello World".

Ensuite, ouvrez le fichier my-app/src/app.js dans votre IDE préféré et modifiez la ligne suivante :

res.send('Hello World');

Remplacez-la par :

res.send('Updated!');

Enregistrez le fichier. Le code Node.js sera automatiquement rechargé et un rafraîchissement de http://localhost:5000 affichera la réponse mise à jour de l'API.

Félicitations, vous disposez maintenant d'une plateforme de développement pleinement opérationnelle !

Installer des packages

Si vous souhaitez installer des packages supplémentaires, vous pouvez exécuter make development-shell pour accéder au shell du conteneur. Une fois à l'intérieur, utilisez NPM avec npm install <package> ou Yarn avec yarn add <package> pour installer les packages souhaités.

Utiliser un projet Node.js existant

Si vous avez déjà un projet Node.js que vous souhaitez intégrer avec Docker, suivez ces étapes :

Créez un nouveau dossier nommé my-app à la racine de votre projet.
Déplacez tous les fichiers de votre projet dans le dossier my-app, à l'exception des fichiers .gitignore et .git.
Copiez les dossiers docker, secrets et le Makefile du boilerplate à la racine de votre projet.
Modifiez le fichier .gitignore de votre projet et ajoutez les lignes suivantes :
```
node_modules/
secrets/*.production
secrets/*.staging
```

Port ouvert

Ce boilerplate suppose que votre application écoute sur le port 5000. Si vous souhaitez utiliser un autre port, modifiez le fichier docker/docker-compose.development.yml puis relancez l'environnement avec make development-start.

Choisir une version spécifique de Node.js

Si vous souhaitez utiliser une version différente de Node.js, procédez comme suit :

Ouvrez le fichier docker/my-app.dockerfile, qui définit l'image Docker de votre application.
Repérez la première ligne qui commence par FROM node:<version>-alpine.
Remplacez <version> par la version de Node.js de votre choix. Il est recommandé d'utiliser la version LTS (Long-Term Support). Vous pouvez consulter la dernière version LTS sur le site Node.js. Par exemple, pour utiliser la dernière version LTS (actuellement 22), modifiez la ligne en FROM node:22-alpine. Si vous souhaitez une version précise, vous pouvez utiliser par exemple FROM node:22.13.0-alpine.
Enregistrez vos modifications dans le Dockerfile.

Variables d'environnement

Définissez les variables d'environnement pour la plateforme de développement dans le fichier secrets/my-app.development.

Pour la production, utilisez le fichier secrets/my-app.production.

Ne validez jamais le fichier secrets/my-app.production dans votre dépôt Git ! Ce fichier contient des informations sensibles et il est ignoré par défaut dans le .gitignore du boilerplate pour éviter tout partage accidentel.

Stocker des fichiers locaux

Si votre application Node.js doit stocker des fichiers (par exemple, des fichiers uploadés par les utilisateurs), il est recommandé d'utiliser un service d'object storage comme MinIO. Un service d'object storage permet à votre application de passer à l'échelle facilement tout en limitant les risques.

Si vous préférez stocker les fichiers localement, veillez à toujours utiliser un volume Docker. Stocker des fichiers directement dans un conteneur peut entraîner une perte de données. Ce boilerplate met à disposition un volume monté sur /persistent pour stocker les fichiers en toute sécurité.

Ne stockez jamais de données persistantes en dehors du dossier /persistent, sauf si vous avez créé des volumes personnalisés et que vous maîtrisez la configuration. Stocker des fichiers en dehors de /persistent entraînera une perte de données !

Ajouter un environnement de staging

Vous pouvez facilement adapter ce boilerplate pour ajouter un environnement de staging. Pour cela :

Faites une copie du fichier docker/docker-compose.production.yml et nommez-la docker/docker-compose.staging.yml. Ce fichier définit les conteneurs et la configuration pour votre environnement de staging.
Créez le fichier de secrets secrets/my-app.staging contenant toutes les informations sensibles nécessaires au staging, comme les mots de passe de base de données ou les clés API.
Dans le Makefile, repérez la section intitulée "Staging platform" et décommentez-la.

Enfin, exécutez make help pour afficher les nouvelles commandes de staging désormais disponibles.

Plateforme de production

Si vous n'avez pas encore de service Stackhero for Docker, vous pouvez en créer un facilement depuis votre tableau de bord Stackhero. Il sera activé en environ 2 minutes.

Si vous découvrez Stackhero, vous pouvez tester l'hébergement cloud de conteneurs Docker gratuitement pendant un mois.

Préparer votre premier déploiement en production

Avant de déployer votre application en production, vous devez préparer quelques fichiers de configuration :

Copiez secrets/global.production.example en secrets/global.production.
Modifiez secrets/global.production et remplacez <XXXXXX>.stackhero-network.com par le nom d'hôte de votre service Docker disponible sur votre tableau de bord Stackhero.
Copiez secrets/my-app.production.example en secrets/my-app.production.
Modifiez secrets/my-app.production et renseignez vos identifiants.
Mettez à jour docker/docker-compose.production.yml en remplaçant <XXXXXX>.stackhero-network.com par le nom d'hôte de votre service Docker.

Déployer en production

Le déploiement en production est très simple : exécutez :

make production-deploy

Cette commande crée un conteneur Docker, transfère les données de votre projet et les envoie sur votre service Docker en production. Ouvrez votre navigateur et accédez au nom d'hôte de votre service Docker (par exemple, https://<XXXXXX>.stackhero-network.com). Vous devriez voir votre API REST répondre "Hello World".

Vous pouvez aussi utiliser make production, qui déploie vos conteneurs et affiche les logs en temps réel.

Afficher les logs

Pour surveiller votre environnement de production ou diagnostiquer un problème, vous pouvez consulter vos logs avec ces commandes :

Pour suivre les logs en temps réel, exécutez : make production-logs-live
Pour récupérer tous les logs stockés, exécutez : make production-logs
Pour afficher les logs d'une journée précise (remplacez YYYY-MM-DD par la date souhaitée), exécutez : make production-logs | grep "YYYY-MM-DD"

Personnaliser les noms de domaine

Si vous souhaitez utiliser un autre nom de domaine que https://<XXXXXX>.stackhero-network.com, Stackhero for Docker intègre Traefik pour simplifier la gestion des domaines. Traefik s'occupe du routage HTTP et du chiffrement TLS (HTTPS) pour vous.

Voici quelques exemples pour personnaliser vos noms de domaine :

Pour servir api.my-company.com via votre conteneur my-app sur le port 5000 avec chiffrement TLS, modifiez le fichier docker/docker-compose.production.yml en remplaçant la section labels par :

    labels:
      - "traefik.enable=true" # Active Traefik pour router le trafic vers ce conteneur
      - "traefik.http.routers.my-app.rule=Host(`api.my-company.com`)" # Définit le host
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt" # Utilise letsencrypt pour les certificats TLS
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Spécifie le port 5000

Pour servir my-company.com via votre conteneur my-app sur le port 5000 et rediriger toutes les requêtes de www.my-company.com vers my-company.com, modifiez la section labels dans le même fichier avec :

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.rule=Host(`my-company.com`) || Host(`www.my-company.com`)" # Inclut les deux domaines
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt"
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Spécifie le port 5000

      # Redirige www.my-company.com vers my-company.com :
      - "traefik.http.routers.my-app.middlewares=redirect-www"
      - "traefik.http.middlewares.redirect-www.redirectregex.regex=^https://www.my-company.com/(.*)"
      - "traefik.http.middlewares.redirect-www.redirectregex.replacement=https://my-company.com/$${1}"
      - "traefik.http.middlewares.redirect-www.redirectregex.permanent=true"

N'oubliez pas de configurer le DNS pour my-company.com et www.my-company.com afin que chacun pointe en CNAME vers votre service Docker à l'adresse https://<XXXXXX>.stackhero-network.com.