NodeServer Generator
Overview
This generator produces an Express-based Node.js server project with all the ingredients you need for a good start at building a cloud native application. You can choose between either a simple web app or microservice pattern. Combine the microservice pattern with a web app for a backend-for-frontend pattern.
Bring your own optional Swagger document to direct code generation for top-down development.
Monitoring and Health
The generated projects are pre-wired for monitoring and health checks. The app includes
Deployment Enablement
The generated projects include deployment configuration for the following environments:
-
Docker
The projects include Docker files to build images for both release and development
-
Kubernetes
The projects include a Helm chart for deployment to Kubernetes.
-
Cloud Foundry
The projects include a manifest for deployment to Cloud Foundry.
-
Dev-ops Pipeline
The projects include a toolchain and pipeline definition for CI/CD deployment to the IBM Cloud.
Special Tools
The projects include NPM scripts to install and run IBM Cloud Developer Tools.
Pre-requisites
Install Yeoman
npm install -g yo
Installation
npm install -g generator-nodeserver
Usage
yo nodeserver
Prompting
When you run 'yo nodeserver', it will prompt you for the following:
-
project name
Specify the project name. It defaults to the current directory name. This is a required value.
-
Swagger doc file name
Specify the relative or absolute file name of a Swagger document to direct the project's code generation. A route stub will be scaffolded and registered for each route defined in the swagger document. This is an optional value.
-
IBM Cloud Service Enablement.
Specify Y|N whether or not you want to scaffold IBM Cloud service enablement into your project. If you specify 'Y', you will be able to select one or more services from a checklist. For each service you select,configuration and access scaffolding code is generated. IBM Cloud service enablement is optional.
Headless mode (without prompting)
Use headless mode to create an app without having to use the UI. This is useful when you want to use this generator to build a project by only running a script instead of interactively.
To create an app using the default options run the command:
yo nodeserver --headless
Defaults:
- Name: the current working directory.
- SwaggerFileName: false.
- Services: false.
Headless usage
To specify the name of the project use:
yo nodeserver --headless='{"name":"your-app-name"}'
To specify which services to add use:
yo nodeserver --headless='{"services":["service1", "service2"]}'
For valid services see below.
Full usage:
yo nodeserver --headless='{"name":"your-app-name","swaggerFileName":"your-swagger-file-name","services":["service1", "service2"]}'
Valid Services
- 'alert notification'
- 'appid'
- 'cloudant'
- 'mongo'
- 'object storage'
- 'postgre'
- 'push'
- 'redis'
- 'watson conversation'
Project Build/Run
Build your generated project one of two ways:
-
Natively, using
npm install
andnpm start
-
Containerized, using IBM Cloud Developer Tools
Note that a containerized approach is supported through the tooling in special consideration of Kubernetes as a deployment environment, following the dev/prod parity principle of 12 Factor Apps.
There are npm scripts to simplify this for you:
-
npm install
-
Install IBM Cloud Developer Tools.
-
npm run idt:build
Builds Docker image for dev mode and does npm install, including dev dependencies.
-
npm run idt:test
Runs project unit tests in dev mode Docker container.
-
npm run idt:debug
Runs the project in debug mode in the dev mode Docker container. The app will start and listen on port 5858 by default for a debug client to attach and take control.
-
npm run idt:run
Runs the project in the release mode Docker container. The release mode Docker container is built without dev dependencies - i.e. with NODE_ENV set to production.
-
Project Deployment
Docker
Build a Docker image and run project in a Docker container using Docker commands in the project root directory:
docker build -t my-image .
docker run -p 3000:3000 --name my-container my-image
Stop and optionally remove the container and image with the following commands:
docker stop my-container
docker rm my-container
docker rmi my-image
Kubernetes Deployment
Deploy to Kubernetes using Helm or the IBM Cloud Developer Tools.
-
Helm
-
Push your image to a Docker image accessible to your Kubernetes environment, such as Docker Hub or your company's private image registry.
-
Install your project from the project's root directory, using the included Helm chart:
helm install chart/
<project name>
--name=<release name>
--set image.repository=<image name>
--set image.tag=<tag value>
--set image.pullPolicy=<pull policy>
Where:
-
<project name>
The name you gave to your project when you generated it.
-
<release name>
An arbitrary name you give to this install instance.
-
<image name>
The registry/image name of your release Docker image - e.g. 'registry.ng.bluemix.net/myspace/myimage'
-
<tag value>
The image tag value of your release Dockerimage - e.g. 'latest' or '1.0.0'
-
<pull policy>
'Always' or 'IfNotPresent'. See Kubernetes image documentation for further explanation.
-
Notes:
-
If the
helm install
command above gives you an error about not finding 'tiller', executehelm init --upgrade
. -
The helm command installs to the Kubernetes environment pointed to by the KUBECONFIG environment variable. Make sure you are in configuration mode for your Kubernetes cluster.
-
The Helm command is installed when you install the IBM Cloud Developer Tools, which you can install for your project by running
npm run idt:install
. -
To delete the helm deployment, execute
helm del --purge <release name>
.
-
-
IBM Cloud Developer Tools
npm run idt:deploy -- --target container
Notes:
-
The idt tool will prompt for registry/image name, then push your image and install your Helm chart to the Kubernetes environment pointed to by your KUBECONFIG environment variable.
-
For IBM Cloud, set KUBECONFIG using the 'bx cs cluster-config
<cluster name>
command. Note this command is installed as part of IBM Cloud Developer Tools, which you can install for your project by running 'npm run idt:install'
-
Clound Foundry Deployment
-
Add a host entry to the "manifest.yml" file (Ex.
host: my-app-name
). -
If you want to connect to a service that is already provisioned in the Cloud, add the instance name in manifest.yml under
services
or replace the placeholder if you indicated a service on project creation -
cf push
Note: if you installed IBM Cloud Developer Tools using the 'npm run idt:install' command, you can run the 'bx cf push' command. Otherwise, install the cf command from Pivotal.
-
IBM Cloud Developer Tools
npm run idt:deploy
This was installed using your project's 'npm run idt:install' script.
Development
Clone this repository and link it via npm
git clone https://github.com/ibm-developer/generator-nodeserver
cd generator-nodeserver
npm link
In a separate directory invoke the generator via
yo nodeserver
Publishing Changes
In order to publish changes, you will need to make a pull request against master
by either fork the repository or creating a new branch against master
.
Make sure to follow the conventional commit specification before contributing. To help you with commit a commit template is provide. Run config.sh
to initialize the commit template to your .git/config
or use commitizen
Once you are finished with your changes, run npm test
to make sure all tests pass. Do a pull request against master
, make sure the build passes. A team member will review and merge your pull request.
Once merged to master
an auto generated pull request will be created against master to update the changelog. Make sure that the CHANGELOG.md and the package.json is correct before merging the pull request. After the auto generated pull request has been merged to master
the version will be bumped and published to npm.