{"id":23627256,"url":"https://github.com/thebumpaster/boilerplate_rest_api_nodejs","last_synced_at":"2026-04-15T14:32:02.633Z","repository":{"id":111013485,"uuid":"404694291","full_name":"TheBumpaster/boilerplate_rest_api_nodejs","owner":"TheBumpaster","description":"Boilerplate ( template ) TypeScript Mongoose Express","archived":false,"fork":false,"pushed_at":"2021-09-10T12:00:12.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T18:15:14.878Z","etag":null,"topics":["express","jwt","moongose","nodejs","rest-api","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheBumpaster.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-09-09T11:23:17.000Z","updated_at":"2022-02-21T08:15:50.000Z","dependencies_parsed_at":"2023-05-13T13:30:54.315Z","dependency_job_id":null,"html_url":"https://github.com/TheBumpaster/boilerplate_rest_api_nodejs","commit_stats":null,"previous_names":[],"tags_count":1,"template":true,"template_full_name":null,"purl":"pkg:github/TheBumpaster/boilerplate_rest_api_nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBumpaster%2Fboilerplate_rest_api_nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBumpaster%2Fboilerplate_rest_api_nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBumpaster%2Fboilerplate_rest_api_nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBumpaster%2Fboilerplate_rest_api_nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheBumpaster","download_url":"https://codeload.github.com/TheBumpaster/boilerplate_rest_api_nodejs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheBumpaster%2Fboilerplate_rest_api_nodejs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272971401,"owners_count":25024093,"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","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["express","jwt","moongose","nodejs","rest-api","typescript"],"created_at":"2024-12-27T23:57:55.871Z","updated_at":"2026-04-15T14:31:57.596Z","avatar_url":"https://github.com/TheBumpaster.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NodeJS REST API Boilerplate\n\n\u003chr\u003e\n\n### Description\nThe goal of this assignment is to build a REST API in NodeJS that is easy scalable and deployable with Docker with minimum API functionality implemented.\n\n## Table of contents\n\n- [Technical Prerequisites](#Technical-Prerequisites)\n- [Getting started](#Getting-started)\n- [Setting up environment](#Setting-up-environment)\n- [Project structure](#Project-structure)\n- [List of packages](#List-of-packages)\n- [Deploy](#Deploying-the-solution-to-Google-Cloud-Console)\n\n## Technical Prerequisites\n- **NodeJS v16**\n- **TypeScript v4.4**\n- **MongoDB v4.2**\n- **Docker v20.10**\n- **Docker Compose v1.29**\n\n\n- Google Cloud SDK (optional)\n  - Google Cloud SDK v356.0.0 \n  - alpha v2021.09.03\n  - beta v2021.09.03\n  - bq v2.0.71\n  - core v2021.09.03 \n  - gsutil v4.67\n\n\n## Getting started\n\n```shell\n# install dependencies\nnpm install\n\n# serve typescript\nnpm run serve\n\n# build source files\nnpm run build\n\n# start server from dist\nnpm run start\n\n# run tests\nnpm run test\n\n# run lint check\nnpm run lint\n\n# generate technical documentation\nnpm run docs\n\n# serve documentation on web http://localhost:5000\nnpm run serve:docs\n```\n\n![img_1.png](media/img_1.png)\n\n### Development\nYou might want to create a new network on docker or update docker-compose service network property.\n```shell\ndocker network create network_name\n```\nTo start a development server stack, build compose images.\n```shell\n# build docker image with docker-compose\ndocker-compose -f docker-compose-yml up -d\n\n# re-build (in case of environment keys updates)\ndocker-compose up docker-compose.yml --build -d\n```\n\nNote: Running docker-compose is for development as it will run `serve` script from package.json.\n\n### Production / Testing / Docker deployment\n```shell\n# Build the image\ndocker build --rm -f Dockerfile -t povio_assignment_server:latest .\n\n# Push image to docker hub\ndocker push --quiet povio_assignment_server:latest\n```\n\nNavigate to `http://localhost:{yourport}/api/docs` for Swagger API Explorer.\n\n![img.png](media/img.png)\n## Setting up environment\n\nThese are required environment keys, they do not have default values.\n\n```dotenv\nPORT=yourServicePortNumber\n\nDB_HOST=yourDatabaseHost\nDB_PORT=yourDatabasePort\nDB_NAME=yourDatabaseName\n\nJWT_SECRET=yourJWTSecretKey\nJWT_ISSUER=yourJWTIssuer\nJWT_AUDIENCE=yourJWTAudience\nJWT_EXPIRY=yourJWTExpiryTime(eg10m)\n\nSECURITY_KEY=yourSecurityKey\nSECURITY_VECTOR=yourSecurityKeyVector\n```\n\n`JWT_SECRET` is important to identify valid user tokens.\n`SECURITY_KEY` is important to be able to compare user password on submission\n`SECURITY_VECTOR` is important to be able to decipher `SECURITY_KEY`\n\nDatabase requires only 3 variables, but can also support few more in case you need them to connect your DB instance to a cluster.\n\n```dotenv\nDB_USER=yourDatabaseUser\nDB_PASS=yourDatabasePassword\nDB_AUTH_SOURCE=yourMongoDBAuthorizationSourceCallback\n```\n\n`NODE_ENV` is being defined by the Docker image or by the Test Suite Environment\n\nTo enable testing environment create a new file in root directory `.env.test` with the following content:\n\n```dotenv\nNODE_ENV=test\nPORT=9999\n\nJWT_SECRET=CatsAndDogs\nJWT_ISSUER=localhost\nJWT_AUDIENCE=localhost:9999\nJWT_EXPIRY=10m\n\nSECURITY_KEY=DogsAndCats\nSECURITY_VECTOR=CatsAndDogs\n```\n\nDatabase keys are not required as they will be autogenerated on initialization of MongoDB MemoryServer. `NODE_ENV=test` is required.\n\n![img_2.png](media/img_2.png)\n\n## Project Structure\n\nProject structure has been taken from MVC principles, but due to event based services I have adjusted it for easier scaling or even splitting into microservices.\n\n```jsonpath\n['povio_assignment']$:\n|-\u003e dist (Generated JavaScript Files)\n|-\u003e docs (Generated Technical Documentation)\n|-\u003e node_modules (Library Root)\n|-\u003e server (TypeScript Source Files)\n|   |-\u003e api (API Module)\n|   |   |-\u003e middleware (API Middlewares)\n|   |   |   |-\u003e authorization.ts (JWT Authentication Middleware)\n|   |   |-\u003e util (API Utilities)\n|   |   |   |-\u003e response.ts (Response Builder)\n|   |   |   |-\u003e security.ts (Password hashing)\n|   |   |-\u003e v1 (API V1 Route Stack)\n|   |   |   |-\u003e health (Probe API Routes)\n|   |   |   |   |-\u003e index.ts (Route Stack)\n|   |   |   |-\u003e system (System API Routes)\n|   |   |   |   |-\u003e index.ts (Router Stack)\n|   |   |   |   |-\u003e validators.ts (Helpers)\n|   |   |   |-\u003e users (Users API Routes)\n|   |   |   |   |-\u003e index.ts (Router Stack)\n|   |   |   |   |-\u003e validators.ts (Helpers)\n|   |   |   |-\u003e api.spec.yaml (OpenAPI V3 Specification)\n|   |   |-\u003e router.ts (Express Router)\n|   |-\u003e config\n|   |   |-\u003e application.ts (Custom environment config)\n|   |   |-\u003e constants.ts (Server global constants)\n|   |-\u003e models\n|   |   |-\u003e users (User Model Module)\n|   |   |   |-\u003e index.ts (Main Model Export)\n|   |   |   |-\u003e schema.ts (User Schema Interface Definition)\n|   |   |   |-\u003e service.ts (User Schema Statics Methods)\n|   |-\u003e services\n|   |   |   |-\u003e database\n|   |   |   |   |-\u003e index.ts (Database client connection methods)\n|   |   |   |-\u003e logger\n|   |   |   |   |-\u003e index.ts (Logger class to utilize winston logger transports and levels)\n|   |-\u003e index.ts (Main Express API Server)\n|-\u003e tests (TypeScript Source Test Files)\n|-\u003e .dockerignore (Ignore files)\n|-\u003e .env (Environment configuration)\n|-\u003e .env.test (Test environment configuration)\n|-\u003e .eslintrc.js (Code Styling Rules)\n|-\u003e .gitignore Ignore files)\n|-\u003e docker-compose.yml (Local Docker Development Stack)\n|-\u003e Dockerfile (Docker Image)\n|-\u003e package.json (NPM package handling)\n|-\u003e readme.md (This File)\n|-\u003e tsconfig.json (TypeScript Configuration)\n|-\u003e typedocs.json (TypeDocs Configuration)\n\n```\n\n## List of packages\n\n- **compression** @ _Node.js compression middleware._\n- **cors** @ _CORS is a node.js package for providing a connect middleware that can be used to enable [CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) with various options._\n- **express** @ _Fast, unopinionated, minimalist web framework for node._\n- **helmet** @ _Helmet helps you secure your Express apps by setting various HTTP headers._\n- **joi** @ _The most powerful schema description language and data validator for JavaScript._\n- **jsonwebtoken** @ _An implementation of JSON Web Tokens_\n- **mongoose** @ _Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment._\n- **swagger-ui-express** @ _This module allows you to serve auto-generated swagger-ui generated API docs from express._\n- **winston** @ _A logger for just about everything._\n- **yaml** @ _JavaScript parser and stringifier for YAML, a human friendly data serialization standard._\n\n# Deploying the solution to Google Cloud Console\n\nI believe Serverless Containers are the future of deploying Containerized applications. The assignment web service runs on Google Cloud Run. I also highly recommend this approach.\n\n1. Download and install Node.js\n2. Select or create a Google Cloud Platform Console project\n3. Enable billing for your project (there's a $300 free trial)\n4. Select or create Atlas Cluster project\n5. Enable billing for your project (there's a free tier) to copy connection string\n6. Do some devops:\n\n```shell\n# Ensure that you have a Live MongoDB URL inside your variable .env\n\n# MongoDB Atlas URI looks like this mongodb://\u003cusername\u003e:\u003cpassword\u003e@\u003chostname\u003e/\u003cdatabase name\u003e\n\n# DB_USER=\u003cusername\u003e\n# DB_PASS=\u003cpassword\u003e\n# DB_HOST=\u003chostname\u003e\n# DB_PORT=\n# DB_NAME=\u003cdatabase name\u003e\n\n# Build a Docker image\ndocker build --rm -f \"Dockerfile\" -t boilerplate_rest_api_nodejs:latest .\n\n# Tag the image to a Google Cloud Container Registry URL\ndocker tag boilerplate_rest_api_nodejs us.gcr.io/[PROJECT ID]/boilerplate_rest_api_nodejs\n\n# Push the newly tagged image to the Google Cloud Container Registry.\ndocker push us.gcr.io/[PROJECT_ID]/boilerplate_rest_api_nodejs\n```\n\nGoogle Container Registry provides secure, private Docker image storage on Google Cloud Platform. Our API follows the Docker Registry API specification, so we are fully compatible with the Docker CLI client, as well as standard tooling using the Docker Registry API.\n\n7. Sign in your Google Cloud Console\n8. Select Container Registry\n9. You will see the latest version of the pushed image.\n10. Select Deploy to Cloud Run \n11. You will be redirected to the Google Cloud Run page.\n12. Fill in the required fields.\n13. Click on CREATE button below your fields. \n14. Congratulations! Your app now runs on Serverless !!!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebumpaster%2Fboilerplate_rest_api_nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthebumpaster%2Fboilerplate_rest_api_nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthebumpaster%2Fboilerplate_rest_api_nodejs/lists"}