{"id":18976606,"url":"https://github.com/paul-schuhm/starterpack-api-nodejs","last_synced_at":"2025-04-19T17:13:40.896Z","repository":{"id":155121288,"uuid":"619497409","full_name":"paul-schuhm/starterpack-api-nodejs","owner":"paul-schuhm","description":"Un kit de développement dockerisé d'une application web Node.js/Express.js pour développer une web API RESTful (à but pédagogique)","archived":false,"fork":false,"pushed_at":"2024-12-18T11:58:48.000Z","size":141,"stargazers_count":1,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T10:43:35.932Z","etag":null,"topics":["development-kit","docker","exercise","express","mysql","nodejs","openapi-specification","rest","restful-api","starter-kit","swagger","teaching-materials"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paul-schuhm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-27T09:01:12.000Z","updated_at":"2024-12-18T11:58:52.000Z","dependencies_parsed_at":"2024-11-07T07:41:19.771Z","dependency_job_id":null,"html_url":"https://github.com/paul-schuhm/starterpack-api-nodejs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fstarterpack-api-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fstarterpack-api-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fstarterpack-api-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paul-schuhm%2Fstarterpack-api-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paul-schuhm","download_url":"https://codeload.github.com/paul-schuhm/starterpack-api-nodejs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249228271,"owners_count":21233852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["development-kit","docker","exercise","express","mysql","nodejs","openapi-specification","rest","restful-api","starter-kit","swagger","teaching-materials"],"created_at":"2024-11-08T15:25:33.847Z","updated_at":"2025-04-16T10:31:51.073Z","avatar_url":"https://github.com/paul-schuhm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Starter pack: *RESTful* web API avec Node.js, Express.js, MySQL et Adminer\n\nUn *starter pack* dockerisé d'une application web node.js pour développer une web API RESTful. L'API vient avec un service de base de données relationnelles (MySQL) et un client graphique (Adminer).\n\n- [Starter pack: *RESTful* web API avec Node.js, Express.js, MySQL et Adminer](#starter-pack-restful-web-api-avec-nodejs-expressjs-mysql-et-adminer)\n  - [Prérequis](#prérequis)\n  - [Lancer le projet](#lancer-le-projet)\n  - [Arrêter le projet](#arrêter-le-projet)\n  - [Tester](#tester)\n  - [La base de données MySQL](#la-base-de-données-mysql)\n  - [Accéder à la base de données](#accéder-à-la-base-de-données)\n    - [avec Adminer](#avec-adminer)\n    - [avec le client mysql depuis votre machine hôte](#avec-le-client-mysql-depuis-votre-machine-hôte)\n    - [depuis un autre conteneur](#depuis-un-autre-conteneur)\n  - [Génération de la documentation OpenAPI avec swagger](#génération-de-la-documentation-openapi-avec-swagger)\n  - [Installer de nouvelles dépendances, inspecter les dépendances](#installer-de-nouvelles-dépendances-inspecter-les-dépendances)\n  - [Conseils pour le développement](#conseils-pour-le-développement)\n  - [Modules Node.js installés](#modules-nodejs-installés)\n  - [Ressources](#ressources)\n    - [Docker](#docker)\n    - [Express](#express)\n    - [Spécification OpenAPI et suite d'outils Swagger](#spécification-openapi-et-suite-doutils-swagger)\n    - [SGBDR et ORM](#sgbdr-et-orm)\n    - [Adminer](#adminer)\n\n\n## Prérequis\n\n- Installer [Docker](https://www.docker.com/get-started/);\n- [Cloner le dépôt](https://github.com/paul-schuhm/starterpack-api-nodejs) et se placer à la racine du projet;\n\n\u003eN'oubliez pas de supprimer le dossier `.git` si vous désirez créer votre propre dépôt à partir des sources\n\n~~~bash\nrm -R .git\ngit init\n~~~\n\n## Lancer le projet\n\n1. **Dupliquer** le fichier `.env.dist` :\n\n~~~bash\ncp .env.dist .env\n~~~\n\n\u003e Vous pouvez modifier les variables d'environnement si vous le souhaitez (des valeurs par défaut sont fournies)\n\n2. **Démarrer le projet** :\n\n~~~bash\ndocker compose watch\n~~~\n\n\u003e Les sources JavaScript sont *watchées*, l'application Node redémarre à chaque édition des sources.\n\n## Arrêter le projet\n\n~~~bash\ndocker compose down\n~~~\n\n## Tester\n\nSe rendre à l'URL [localhost:5001](http://localhost:5001), ou avec [curl](https://curl.se/) :\n\n~~~bash\ncurl -i localhost:5001\n~~~\n\nVous devriez voir une page HTML qui affiche des données issues de la base de données MySQL.\n\n\u003e Attendez quelques secondes que le serveur MySQL soit prêt à accepter des requêtes.\n\n## La base de données MySQL\n\n\u003ePenser à modifier la valeur du port si vous l'avez changé dans le `.env`\n\nLa base de données vient avec deux utilisateurs :\n\n- `root` (administrateur), mot de passe : `root`\n- `user` (utilisateur lambda), mot de passe : `password`\n\n\n## Accéder à la base de données\n\n### avec Adminer\n\nLe projet vient avec [Adminer](https://www.adminer.org/), un gestionnaire de base de données avec interface graphique, simple et puissant.\n\nSe rendre sur l'URL [http://localhost:5003](http://localhost:5003) (par défaut) et se connecter avec les credentials root ou user.\n\n### avec le client mysql depuis votre machine hôte\n\n~~~bash\nmysql -uroot -proot -Dmydb -h127.0.0.1 -P5002\n~~~\n\n\u003e*Machine hôte* : la machine sur laquelle s’exécute les conteneurs Docker, *votre* machine\n\nPuis, dans le repl MySQL (session ouverte avec la commande précédente)\n\n~~~SQL\n-- Lister les utilisateurs MySQL\nSELECT user FROM mysql.user;\n-- Lister les users dans la base de départ\nSELECT * FROM User;\n~~~\n\n\u003e **Préférer utiliser l'adresse IP `127.0.0.1` plutôt que son alias `localhost`** afin éviter des potentiels conflits de configuration avec le fichier [socket](https://www.jetbrains.com/help/datagrip/how-to-connect-to-mysql-with-unix-sockets.html) du serveur MySQL potentiellement installé sur votre machine hôte.\n\n### depuis un autre conteneur\n\nLe nom de l'hôte est `db`, le nom du service sur le réseau Docker.\n\n\n\u003c!-- \nDepuis un script PHP sur la machine hote : \n\n- new PDO('mysql:host=localhost:5002;dbname=mydb', $user, $pass); OK\n- new PDO('mysql:host=127.0.0.1:5002;dbname=mydb', $user, $pass); OK\n- new PDO('mysql:host=127.0.0.1;dbname=mydb;port=5002', $user, $pass); OK\n- new PDO('mysql:host=localhost;dbname=mydb;port=5002', $user, $pass); ERREUR ! Ici le port est ignoré et la connexion se fait par le socket de l'installation de mysql sur ma machine hote. Donc, le script PHP ne requête pas le serveur MySQL sur le conteneur mais celui sur ma machine hote. Cela se voit si on arrete le service MySQL sur la machine hote (systemctl stop/restart mysql)\n~~~php\n//Exemple en PHP\n\u003c?php\n$user='root';\n$pass='root';\n$dbh = new PDO('mysql:host=127.0.0.1;port=5002;dbname=mydb', $user, $pass);\n$ps = $dbh-\u003equery('SELECT * FROM User;');\n$users = $ps-\u003efetchAll();\nvar_dump($users);\n~~~\n\nDifférence entre utiliser 127.0.0.1 et localhost :\n\nLorsque vous utilisez l'hôte \"localhost\", PDO essaie de se connecter à MySQL en utilisant un socket local plutôt que par TCP/IP. Le chemin du socket varie en fonction de la configuration de MySQL et de votre système.\n\nLorsque vous utilisez \"127.0.0.1\" comme hôte, PDO se connecte à MySQL en utilisant TCP/IP sur le port par défaut (généralement 3306) au lieu d'utiliser un socket local, sauf si le port est spécifié dans le DSN. Cela peut contourner les problèmes liés à la résolution du nom de socket local.\n\nEn conclusion : préférer utiliser 127.0.0.1 plutot que localhost pout s'épargner des conflits de configuration et être sûr de requêter le serveur MySQL conteneurisé.\n --\u003e\n\n## Génération de la documentation OpenAPI avec swagger\n\n(Re)générer la documentation interactive de votre API avec le module [swagger-autogen](https://www.npmjs.com/package/swagger-autogen) (déjà installé):\n\n~~~bash\ndocker exec -it demo-rest-api-api npm run swagger-autogen\n~~~\n\nSe rendre à l'URL `/doc` pour accéder à Swagger UI et à la documentation interactive de votre API.\n\n## Installer de nouvelles dépendances, inspecter les dépendances\n\nVous pouvez installer de nouvelles dépendances au besoin. À la racine de l'application, installer les dépendances désirées *via* `npm`:\n\n~~~bash\ndocker exec -it demo-rest-api-api npm install \u003cle nom du paquet\u003e\n~~~\n\nou directement sur la machine hôte (changements seront repercutés par le watch des sources):\n\n~~~bash\nnpm install \u003cle nom du paquet\u003e\n~~~\n\nLister les dépendances du projet Node:\n\n~~~bash\ndocker exec -it demo-rest-api-api npm list\n~~~\n\n## Conseils pour le développement\n\n- **Débuger** : Inspecter les *logs* du conteneur Docker (`docker logs -f demo-rest-api-api`, ou via Docker Desktop ou via l'[extension officielle Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)) qui contiennent tout ce qui est écrit sur la sortie standard (avec `console.log()`). Les sources de l'application Node.js sont *watchées*, donc à chaque modification d'un fichier source l'application redémarre pour les prendre en compte automatiquement ;\n- Ouvrez une connexion MySQL pendant votre développement pour tester vos requêtes *avant* de les intégrer dans votre code;\n- Utiliser cURL pour tester rapidement vos requêtes HTTP. \n- Ouvrez deux terminaux: l'un avec cURL et l'autre avec les logs de l'API pour débuger facilement votre système;\n- Installer le module `dotenv` pour placer le DSN (informations de connexion à la base) en dehors du code;\n- Pour tester des enchaînements de requêtes, écrivez un script SQL pour remettre la base dans un état initial et contenant les requêtes à tester, un script pour effectuer les requêtes HTTP avec cURL, et exécuter le tout en **une commande** (en vous servant de l'opérateur du shell `\u0026\u0026`).\n\n## Modules Node.js installés\n\n- [express](https://expressjs.com/) ;\n- [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken), une implémentation javascript du standard JSON Web Token, voir [RFC 7519](https://www.rfc-editor.org/rfc/rfc7519) ;\n- [cors](https://www.npmjs.com/package/cors), un module middleware pour gérer la politique CORS (*Cross Origin Resource Sharing*);\n- [mysql2](https://www.npmjs.com/package/mysql2), un client MySQL pour Node.js qui [utilise l'API des promesses](https://www.npmjs.com/package/mysql2#using-promise-wrapper) (contrairement à son prédécesseur [mysql](https://www.npmjs.com/package/mysql));\n\n\n## Ressources\n\n### Docker\n\n- [Image Docker Node](https://hub.docker.com/_/node)\n- [Image Docker MySQL](https://hub.docker.com/_/mysql)\n- [Image Docker Adminer](https://hub.docker.com/_/adminer/)\n- [Dockerizing a Node.js web app](https://nodejs.org/en/docs/guides/nodejs-docker-webapp)\n\n### Express\n\n- [Générateur d’applications Express](https://expressjs.com/fr/starter/generator.html), générer un projet pour démarrer\n- [Routage](https://expressjs.com/fr/guide/routing.html), la documentation sur le routage d'Express\n- [Pug](https://pugjs.org/api/getting-started.html), moteur de templates javascript installé par défaut avec Express\n- [API JSON Web Token Authentication (JWT) sur Express.js](https://etienner.github.io/api-json-web-token-authentication-jwt-sur-express-js/), un bon tutoriel pour mettre en place des routes protégées par Json Web Token\n\n### Spécification OpenAPI et suite d'outils Swagger\n\n- [Swagger UI](https://swagger.io/tools/swagger-ui/), servir une documentation web interactive de l'API à partir de [sa description OpenAPi](https://spec.openapis.org/oas/v3.1.0#openapi-specification) (même si elle devrait être *par définition* auto-documentée et *auto-descriptive*, c'est toujours appréciable)\n- [Swagger UI Express](https://www.npmjs.com/package/swagger-ui-express), module Node.js pour intégrer Swagger UI à un projet Node.js;\n- [Swagger auto-gen](https://www.npmjs.com/package/swagger-autogen), module de génération *automatique* de la description OpenAPI de l'API à partir des métadonnées placées dans les sources d'une application Node.js/Express;\n- [Swagger auto-gen: décrire des paramètres de formulaire POST](https://www.npmjs.com/package/swagger-autogen#parameters)\n- [The OpenAPI Specification Explained](https://learn.openapis.org/specification/), **le guide**\n- [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0#openapi-specification), **la référence complète**, pour décrire votre API au format YAML ou JSON; \n- [Documentation de swagger auto-gen](https://swagger-autogen.github.io/docs/getting-started/), documentation sur les tags à inclure dans les sources pour générer l'OpenAPI Description fil. Attention à [bien utiliser la version OpenAPI 3.x](https://swagger-autogen.github.io/docs/openapi-3/)\n\n\n### SGBDR et ORM\n\n- [MySQL Docker Image, quick reference](https://hub.docker.com/_/mysql/)\n- [mysql2](https://www.npmjs.com/package/mysql2), le driver node.js pour le SGBDR MySQL qui implémente l'API des promesses (contrairement à [mysql](https://www.npmjs.com/package/mysql))\n- [Sequelize, Getting Started](https://sequelize.org/docs/v6/getting-started/), Sequelize, un ORM pour Node.js\n\n### Adminer\n\n- [Adminer](https://www.adminer.org/)\n\n\n\u003c!-- \nHealhtcheck: ne redémarre pas le conteneur si unhealthy (valeur différente de 0). Sert juste à mettre la valeur d'un label. Ce label est utilisé par Swarm par exemple. Mais avec depends_on on peut ajouter un test de santé du conteneur dont ont dépend. https://docs.docker.com/reference/compose-file/services/#depends_on, https://docs.docker.com/reference/compose-file/services/#long-syntax-1\n --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaul-schuhm%2Fstarterpack-api-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaul-schuhm%2Fstarterpack-api-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaul-schuhm%2Fstarterpack-api-nodejs/lists"}