configuration.md

copyright	years 2018
lastupdated	2018-08-20

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:codeblock: .codeblock} {:pre: .pre} {:tip: .tip}

Configuring the Node.js environment

{: #healthcheck}

Ideally, a Node.js application is able to move from one environment to another (for example, from testing into production) without changing code, or exercising otherwise untested code paths.

The problem arises when significant differences exist in the way the config is presented, depending on the development environment. For example, CloudFoundry, which uses stringified JSON objects versus Kubernetes that uses either flat values or stringified JSON objects. Local development outside of Kubernetes has different considerations as well. Credentials can be presented differently across public and private, which further make it difficult for apps to remain unchanged across environments.

Whether you need to add Cloud support to existing applications or create apps with Starter kits, the goal is to provide maximum portability for Node.js apps regardless of the development platform.

Adding Cloud support to existing Node.js applications

{: #addcloud-env}

The ibm-cloud-env module aggregates environment variables from various Cloud providers, such as CloudFoundry and Kubernetes, so the application remains environment-agnostic.

Installing the ibm-cloud-env module

1. Install the ibm-cloud-env module with the following command:

npm install ibm-cloud-env

{: codeblock}

2. Initialize the module in your code by referencing the mappings.json file that contains your mappings:

const IBMCloudEnv = require('ibm-cloud-env');
IBMCloudEnv.init("/path/to/the/mappings/file/relative/to/prject/root");

{: codeblock}

If the mappings file path is not specified in the IBMCloudEnv.init(), the module tries to load mappings from a default path of /server/config/mappings.json. {: tip}

Example mappings.json file:

{
  "service1-credentials": {
      "searchPatterns": [
          "cloudfoundry:my-service1-instance-name", 
          "env:my-service1-credentials", 
          "file:/localdev/my-service1-credentials.json" 
      ]
  },
  "service2-username": {
      "searchPatterns":[
          "cloudfoundry:$.service2[@.name=='my-service2-instance-name'].credentials.username",
          "env:my-service2-credentials:$.username",
          "file:/localdev/my-service1-credentials.json:$.username" 
      ]
  }
}

{: codeblock}

Using the values in a Node.js app

Retrieve the values in your application by using the following commands.

1. Retrieve variable service1credentials:

// this will be a dictionary
var service1credentials = IBMCloudEnv.getDictionary("service1-credentials");

{: codeblock}

2. Retrieve variable service2username:

var service2username = IBMCloudEnv.getString("service2-username"); // this will be a string

{: codeblock}

Now your application can be implemented in a runtime environment-agnostic way, by abstracting the differences that are introduced from different Cloud compute providers.

Filtering the values for tags and labels

You can filter credentials that are generated by the module based on service tags, and service labels as shown in the following example:

var filtered_credentials = IBMCloudEnv.getCredentialsForServiceLabel('tag', 'label', credentials)); // returns a Json with credentials for specified service tag and label

{: codeblock}

Using the Node.js configuration manager from Starter Kit apps

Node.js apps that are created with Starter Kits automatically come with credentials and configuration that is needed to run in many Cloud deployment environments (CF, K8s, VSI, and Functions).

Understanding the mappings file that is produced by generators

• The mappings file is expected to have the same structure regardless of the language (java/node/swift/python).
• The location of the mappings file is appropriate for the language and framework.
• The mappings file can be either auto-generated or manually written.
• The mappings file is used to define an array of searchPatterns.
• searchPatterns are processed in the order that they are declared in the array.
• searchPatterns support JSONPath.
• The mappings file is generated by the Yeoman generator (service-enablement-generator). Each service sub-generator is able to inject the required values.

Understanding service credentials

Your application configuration information for services is stored in the localdev-config.json file in the /server/config directory. The file is in the .gitignore directory to prevent sensitive information from being stored in Git. The connection information for any configured service that runs locally, such as user name, password, and host name, is stored in this file.

The application uses the configuration manager to read the connection and configuration information from the environment, and this file. It uses a custom built mappings.json, found in the server/config directory, to communicate where the credentials can be found for each service.

If the application is running locally, it can connect to {{site.data.keyword.cloud_notm}} services by using unbound credentials read from this file. If you need to create unbound credentials you can do so from the {{site.data.keyword.cloud_notm}} web console (example), or by using the CloudFoundry CLI cf create-service-key command.

When you push your application to {{site.data.keyword.cloud_notm}}, these values are no longer used. Instead, the application automatically connects to bound services by using environment variables.

• Cloud Foundry: Service credentials are taken from the VCAP_SERVICES environment variable.

• Kubernetes: Service credentials are taken from individual environment variables per service.

• {{site.data.keyword.cloud_notm}} Container Service: Service credentials are taken from VSIs or {{site.data.keyword.openwhisk}} (Openwhisk).

Next Steps

{: #next_steps notoc}

The ibm-cloud-config supports searching for values by using three search pattern types, cloudfoundry, env, and file. If you would like to check out other supported search patterns and search pattern examples, check the Usage section.