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 offrant de nombreux avantages, notamment :

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

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

Performance optimale et sécurité robuste 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 d'hébergement cloud Docker CaaS de Stackhero et déployer vos containers en production !

Ce guide 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 requise. Tout est configuré pour garantir une expérience fluide ; il vous suffit d'avoir Docker installé sur votre ordinateur.

Cette documentation est conçue pour les débutants comme pour les utilisateurs expérimentés souhaitant déployer une application Node.js en utilisant des technologies modernes et évolutives sans complications inutiles.

Les principales caractéristiques de cette solution incluent :

💪 Configuration facile avec un minimum d'effort
🐳 Utilisation de Docker pour les environnements de développement et de production
🔄 Rechargement automatique de Node.js lors des modifications de code avec nodemon
🚀 Déploiement en production en une seule commande
🔒 Gestion des certificats TLS pour un chiffrement HTTPS sécurisé
🚧 Support pour les 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 aucune erreur.

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

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

Ensuite, démarrez la plateforme de développement en exécutant make development-start ou consultez 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, l'exécute et lance le script dev défini dans my-app/package.json (ce qui équivaut à exécuter npm run dev).

Dans cet exemple, une simple API REST utilisant Express est créée. Vous pouvez visualiser l'API en naviguant vers http://localhost:5000. La page devrait 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');

Changez-la en :

res.send('Updated!');

Enregistrez le fichier. Le code Node.js se rechargera automatiquement et un rafraîchissement de http://localhost:5000 reflétera la réponse API mise à jour.

Félicitations - vous avez maintenant une plateforme de développement entièrement opérationnelle !

Installer des packages

Si vous avez besoin d'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 vos packages souhaités.

Utiliser un projet Node.js existant

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

Créez un nouveau répertoire appelé my-app à l'intérieur de votre projet.
Déplacez tous vos fichiers de projet dans le répertoire my-app, à l'exception des fichiers .gitignore et .git.
Copiez le docker, secrets, et Makefile du boilerplate dans le répertoire racine de votre projet.
Modifiez le fichier .gitignore dans 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 préférez un autre port, vous pouvez modifier le fichier docker/docker-compose.development.yml puis relancer l'environnement avec make development-start.

Choisir une version spécifique de Node.js

Si vous souhaitez spécifier une version différente de Node.js, suivez ces étapes :

Ouvrez le fichier docker/my-app.dockerfile, qui définit l'image Docker pour votre application.
Localisez la première ligne qui lit FROM node:<version>-alpine.
Remplacez <version> par la version de Node.js de votre choix. Il est recommandé d'utiliser la version Long-Term Support (LTS). Vous pouvez vérifier la dernière version LTS sur le site de Node.js. Par exemple, pour utiliser la dernière version LTS (actuellement 22), mettez à jour la ligne en FROM node:22-alpine. Si vous préférez un numéro de version spécifique, vous pouvez utiliser quelque chose comme 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 commettez pas le fichier secrets/my-app.production dans votre dépôt Git ! Ce fichier contient des informations sensibles et 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 téléchargements d'utilisateurs), envisagez d'utiliser un service d'object storage tel que MinIO. Un service d'object storage aide votre application à évoluer sans problème tout en réduisant les problèmes potentiels.

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

Ne stockez jamais de données persistantes en dehors du répertoire /persistent à moins d'avoir créé des volumes personnalisés et d'être certain de la configuration. Stocker des fichiers en dehors de /persistent entraînera une perte de données !

Ajouter un environnement de staging

Vous pouvez facilement modifier ce boilerplate pour ajouter un environnement de staging. Pour ce faire :

Créez une copie de 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 toute information sensible requise pour le staging, comme les mots de passe de base de données ou les clés API.
Dans le Makefile, localisez la section intitulée "Staging platform" et décommentez-la.

Enfin, exécutez make help pour voir 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 êtes nouveau sur Stackhero, vous pouvez essayer 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 depuis votre tableau de bord Stackhero.
Copiez secrets/my-app.production.example en secrets/my-app.production.
Modifiez secrets/my-app.production et insérez 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 simple : exécutez :

make production-deploy

Cette commande crée un conteneur Docker, transfère les données de votre projet et les envoie à votre service Docker en production. Ouvrez votre navigateur et naviguez vers le 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 également 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 résoudre des problèmes, vous pouvez consulter vos logs en utilisant ces commandes :

Pour diffuser les logs en direct, exécutez : make production-logs-live
Pour récupérer tous les logs stockés, exécutez : make production-logs
Pour récupérer les logs d'un jour spécifique (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 nom de domaine différent de https://<XXXXXX>.stackhero-network.com, Stackhero for Docker intègre Traefik pour simplifier la gestion des domaines. Traefik gère le routage HTTP et le 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, mettez à jour le fichier docker/docker-compose.production.yml en remplaçant la section labels par :

    labels:
      - "traefik.enable=true" # Activer Traefik pour router le trafic vers ce conteneur
      - "traefik.http.routers.my-app.rule=Host(`api.my-company.com`)" # Définir l'hôte
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt" # Utiliser letsencrypt pour les certificats TLS
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Spécifier 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, mettez à jour 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`)" # Inclure les deux domaines
      - "traefik.http.routers.my-app.tls.certresolver=letsencrypt"
      - "traefik.http.services.my-app.loadbalancer.server.port=5000" # Spécifier le port 5000

      # Rediriger 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 tant que CNAME vers votre service Docker à https://<XXXXXX>.stackhero-network.com.