Search

Runtime Configuration for Node.js

Concept & Usage


How to Configure

How It Works

You can maintain your configuration in several ways. Here is a sample configuration using .cdsrc.json and package.json and the resulting effective configuration.

  1. Your .cdsrc.json
     "build": { "target": ".out" },
     "i18n": { "default_language": "de" } ,
     "deploy": { "no_save": true }
    
    
  2. Your package.json
     "cds": {
        "build": { "target": "genfolder" },
        "i18n": { "default_language": "de" } ,
        "deploy": { "no_save": true }
     }
    

For Node.js, this results in an effective configuration:

cds.env.build.target --> "genfolder"
cds.env.i18n.default_language  -->  "de"
cds.env.deploy.no_save  -->  true

Environment Variables

Single properties can be set by using environment variables with prefix CDS_ as in CDS_BUILD_TARGET = "genfolder".

Structured configuration is passed by the special environment variable CDS_CONFIG. It contains a JSON string similar to the cds section in package.json (no cds node required in CDS_CONFIG). Environment variables for single properties have higher precedence than CDS_CONFIG.

The environment mock file default-env.json is supported. Entries in this file act like setting environment variables, in case the real variables haven’t been set.

Dependencies

Dependencies to databases and services can be configured by listing them within a requires section.

The subnodes below requires are static names, which can be referenced in coding as well (cds.env.requires.orderdata.credentials...).

package.json

"cds": {
   "requires": {
      "db": {    // a static name identifying this dependency.
        "kind": "hana",
        "model": "srv-hana",
        "credentials": {}   // can be explicitly configured here,
                            // but will be overruled by VCAP_SERVICES
                            // if a matching entry is found therein.
	  },
      "uaa": {
         "kind": "xsuaa",
         "credentials": { }
      }
   }
}

Not all dependencies can be found in VCAP_SERVICES (for example, "kind": "sqlite").

Matching to VCAP_SERVICES

If VCAP_SERVICES is present, then credentials for dependencies must be taken from this variable. The existing subnodes of requires are matched against VCAP_SERVICES. There are multiple matching methods that are applied in order. If one match is found, the matching entry is taken over into the effective configuration. The remaining matching methods aren’t executed.

Explicit Configuration

You explicitly configure the subproperty vcap.name using a configuration file, environment variable, or command line. This configuration affects the effective configuration before matching to VCAP_SERVICES. So, if vcap.name has been configured, the match is based on the value for vcap.name. Using such a configuration, can disambiguate the “space sharing” scenario as well.

We’re using YAML notation for representing effective configurations:

Explicit match

Example:

Set cds.env.requires.db.vcap.name using the environment variable: CDS_REQUIRES_DB_VCAP_NAME.


Simple Match

The name of the requires subnode is matched against name in VCAP_SERVICES. The match is successful if there’s exactly one match.

Simple match

The easiest option is to create a service instance with the same name as used in the requires section.

If you share one Cloud Foundry space with multiple developers, you can achieve separation by using multiple service instances with different names. In this case, they shall specify a binding_name when creating the service binding on Cloud Foundry. binding_name must then match the name of the requires section.

Simple match


Service Tags

When sharing a space, as an alternative to use a binding_name, you can set a tag to enable the match. For instance, using the command line:

cf create-service hana hdi-shared mydb -t "cds:db"

match by tags

Heuristics

If none of the above methods are applicable, then two heuristic methods are applied.

First, kind is compared to the content of the tag array in VCAP_SERVICES. If a match is found, search is completed and the matching credentials are returned.

If this method doesn’t lead to a match, kind is compared to the label property in VCAP_SERVICES.

Heuristics

This works, because label is supposed to reflect the “name of the service offering” and because we choose the list of kind in accordance with the SAP Cloud Platform Service Broker Catalog.

Profiles

Profiles are a means to override default configuration values in configuration files. To override configuration comes in handy if you want to start the application with a deviating configuration.

Usage

In this sample .cdsrc.json, the requires section at the top is the default configuration to connect to SAP HANA. Then, for SQLite, a profile named development is introduced through the [...] notation. It overrides the default configuration if the development profile is active.

{
   "requires": {
      "db":  { "kind": "hana" }
   },
   "[development]": {
      "requires": {
         "db": {
            "kind": "sqlite",
            "credentials": { "database": "my.db" }
         }
      }
   }
}

Activation

Profiles are activated through the environment variable NODE_ENV. If NODE_ENV is not set, the profile development is activated, a convention adopted by many Node.js applications interpreting NODE_ENV. Usually, in continuous integration (CI) builds and Cloud Foundry deployments, NODE_ENV is set to production automatically.

Launch a Node.js server with the ad hoc activated production profile:

Effective Configuration

Use cds env to list the effective configuration, which has all configuration files and profiles merged.

Single blocks or values can be read through cds env get. For example cds env get requires lists the requires block from the CDS configuration.

The effective configuration highly depends on the working directory and the current process or shell environment. Use cds env src to list all sources of configuration, that is, all files from which configuration is read.

Use cds help env to see all options.

Note that not all configuration keys are public APIs. When referring to a key, consult the documentation of the respective tool to find out.

Application Configuration

An application can add its own configuration properties, which are then made available in the effective environment following the same rules as for cds configuration.

EXAMPLE:

package.json:


"myapp": {
   "prop1": "value1",
   "prop2": "value2"
}

Environment variable MYAPP_PROP2 = “valueX”.

For Node.js, we provide an API to load the configuration node “myapp”:

let c = cds.env.for('myapp')  //> c = {prop1: 'value1', prop2: 'valueX'}