kth-node-configuration

    2.0.12 • Public • Published

    kth-node-configuration Build Status

    Configuration module for Node.js projects.

    Usage

    node-api projects

    In node-api projects you only have a single settings file called serverSettings.js. Create your configuration by adding the following code:

    'use strict'
    const { generateConfig } = require('kth-node-configuration')
    
    // These settings are used by the server
    const serverConfig = generateConfig([require('../../../config/serverSettings')])
    
    module.exports.server = serverConfig

    All options are available in this object.

    node-web projects

    In node-web projects your settings are split in three files:

    • commonSettings.js -- settings shared by browser and server (i.e. don't store any secrets here)
    • browserSettings.js -- settings passed to the browser (i.e. don't store any secrets here either)
    • serverSettings.js -- settings that are specific to the server

    If you use LDAP you will also want to add default LDAP settings to your server config.

    'use strict'
    const { generateConfig } = require('kth-node-configuration')
    // The ldapDefaultSettings contains ldapClient defaults object
    const ldapDefaultSettings = require('kth-node-configuration').unpackLDAPConfig.defaultSettings
    
    // These settings are used by the server
    const serverConfig = generateConfig([
      ldapDefaultSettings,
      require('../../../config/commonSettings'),
      require('../../../config/serverSettings')
    ])
    
    module.exports.server = serverConfig
    
    // These settings are passed to the browser
    const browserConfig = generateConfig([
      require('../../../config/commonSettings'),
      require('../../../config/browserSettings')
    ])
    
    module.exports.browser = browserConfig

    Helper methods

    There are a couple of helper methods available to allow your settings files to be a bit more concise.

    The env-vars should be on the same form as the default URI.

    Options override any settings you pass through env-vars or defaults.

    NOTE: the helper methods obey standard URI syntax. Any get params you add will be set as properties on the config object.

    Escaping

    Don't forget to escape special characters such as:

    • '&' in keys to '%26'
    • '/' in usernames or passwords to '%2F'

    unpackApiKeysConfig(ENV_VAR_NAME_URI, defaultURI)

    This call returns an array of api access key objects.

    const defaultUri = '?name=devClient&apiKey=1234&scope=write&scope=read'
    unpackApiKeysConfig('API_KEYS', defaultUri)

    To define multiple API_KEYS you name each key as if it was a reference to an array. The unpacker will iterate from 0 and add each item until it comes across a value that is undefined:

    API_KEYS_0 = '?name=devClient&apiKey=1234&scope=write&scope=read'
    API_KEYS_1 = '?name=devClient&apiKey=1234&scope=write&scope=read'
    API_KEYS_2 = '?name=devClient&apiKey=1234&scope=write&scope=read'
    

    unpackKOPPSConfig(ENV_VAR_NAME_URI, defaultURI [, options])

    const defaultUri = 'http://[hostname][:port][/path]?defaultTimeout=60000'
    unpackKOPPSConfig('KOPPS_URI', defaultUri)

    unpackLDAPConfig(ENV_VAR_NAME_URI, ENV_VAR_NAME_PASSWORD, defaultURI [, options])

    // Never hard code defaults to LDAP in settings, always pass through env-vars
    // LDAP_URI = 'ldaps://[username]@[hostname]:[port]
    // LDAP_PASSWORD = 'yadayada'
    unpackLDAPConfig('LDAP_URI', 'LDAP_PASSWORD')

    NOTE 1: Some default settings are always applied and can be overridden by passing options. Check source for defaults.

    NOTE 2: Having a separate config.ldap and config.ldapClient configuration is deprecated, everything should be in config.ldap.

    NOTE 3: upackRedisConfig supports Azure connection string

    unpackMongodbConfig(ENV_VAR_NAME_URI, defaultURI [, options])

    const defaultUri = 'mongodb://[hostname][:port][/path][?ssl=true]'
    unpackMongodbConfig('MONGODB_URI', defaultUri)

    unpackNodeApiConfig(ENV_VAR_NAME_URI, defaultURI [, options])

    const defaultUri = 'http[s]://[hostname][:port][/path][?required=true&defaultTimeout=10000]'
    unpackNodeApiConfig('NODE_API_URI', defaultUri)

    unpackRedisConfig(ENV_VAR_NAME_URI, defaultURI [, options])

    const defaultUri = 'redis://[hostname][:port]/'
    unpackRedisConfig('REDIS_URI', defaultUri)

    unpackSMTPConfig(ENV_VAR_NAME_URI, defaultURI [, options])

    // Never include username or password in default SMTP-config
    const defaultUri = 'smtp://smtp.kth.se:25'
    // SMTP_URI = smtp[s]://[username][:password]@[hostname]:[port]
    unpackSMTPConfig('SMTP_URI', defaultUri)

    unpackSequelizeConfig(ENV_VAR_NAME_URI, defaultURI [, options])

    // Never include username or password in default SMTP-config
    const defaultSQLiteUri = 'sqlite://path/to/db.file'
    // DB_URI = sqlite://[path/to/file]
    const defaultSQLServerUri = 'mssql://username@db.test.com/InstanceName/DbName'
    // DB_URI = mssql://[username][:password]@[hostname]:[port]/[DbInstance]/[DbName]
    unpackSequelizeConfig('DB_URI', 'DB_PWD', defaultUri)

    Examples of usage can be found int the node-api and node-web template projects.

    Dotenv

    Use the npm package dotenv to set environment variables during development. Take a look at the unit tests for example usage.

    This code snippet loads env-vars with dotenv during development. In production it checks for the availability of SERVICE_PUBLISH which is always set in a KTH Docker environment. If it isn't found it will require localSettings.js which is the standard settings file in the KTH Ansible environment. There you can set env-vars by process.env.ENV_VAR = 'value'

    // Load .env file in development mode
    const nodeEnv = process.env.NODE_ENV && process.env.NODE_ENV.toLowerCase()
    if (nodeEnv === 'development' || nodeEnv === 'dev' || !nodeEnv) {
      require('dotenv').config()
    } else if (!process.env.SERVICE_PUBLISH) {
      // This is an ANSIBLE machine which doesn't set env-vars atm
      // so read localSettings.js which we now use to fake env-vars
      // because it already exists in our Ansible setup.
      require('../config/localSettings')
    }

    DEV NOTES

    • vi fimpar local-/prod-/ref-/devSettings.js

      • läggs i commonSettings.js, serverSettings.js, browserSettings.js
    • fimpa full, safe och secure

    När vi skapar nya settings-objektet

    • vi mergear commonSettings.js + serverSettings.js till servern
    • vi mergear commonSettings.js + browserSettings.js till browsern
      • returneras på endpointen ./browserConfig som javascript TODO: - lägg till script-tag i början av all layout-filer

    Migrating from <= 1.0.1

    • convert ...Settings.js files to:

      • commonSettings.js -- shared by browser and server
      • serverSettings.js -- server specific settings that should NEVER be sent to a browser
      • browserSettings.js -- browser specific settings that are passed to browser
    • Search and replace:

      require('../**/configuration') => require('../**/configuration').server
    
    • config.full => config

    • config.safe => config

    • [xxx].secure => [xxx]

    • server.full => server

    • What are these used for (kth-node-configuration)

      • module.exports.getEnv = _env
      • module.exports.getEnvString = _str
      • module.exports.getEnvBool = _bool
      • module.exports.getEnvInt = _int
      • module.exports.devDefaults = _str
    • Update tests

      config.full => config

    • change how we start server:

      kth-node-server@1.x:

      server.setConfig(config) => server.setConfig({ full: config })

      kth-node-server@3.x:

    server.start({
      pfx: config.ssl.pfx,
      passphrase: config.ssl.passphrase,
      key: config.ssl.key,
      ca: config.ssl.ca,
      cert: config.ssl.cert,
      port: config.port,
      logger: log // Your logging service, could be console or kth-node-log
    })
    • change in adldap.js (only if we use ldap)

      • attributes: config.ldapClient.userattrs => attributes: config.ldap.userattrs
      • config.ldapClient.filterReplaceHolder, kthid => config.ldap.filterReplaceHolder, kthid
    • change configuration.js (examples for node-web and node-api apps)

    app.js Edit app.js to look like this:

    'use strict'
    
    const server = require('./server/server')
    require('./server/init')

    NODE-WEB:

    'use strict'
    const { generateConfig } = require('kth-node-configuration')
    
    // These settings are used by the server
    const serverConfig = generateConfig([
      require('../../../config/commonSettings'),
      require('../../../config/serverSettings')
    ])
    
    module.exports.server = serverConfig
    
    // These settings are passed to the browser
    const browserConfig = generateConfig([
      require('../../../config/commonSettings'),
      require('../../../config/browserSettings')
    ])
    
    module.exports.browser = browserConfig

    In adldap.js you need to change:

    • config.ldapClient => config.ldap

    And move any config settings from ldapClient object to ldap object.

    NODE-API:

    'use strict'
    const { generateConfig } = require('kth-node-configuration')
    
    // These settings are used by the server
    const serverConfig = generateConfig([require('../../../config/serverSettings')])
    
    module.exports.server = serverConfig
    • add dependency to dotenv and have it load your .env-file on startup. server.js should start like this:
    const server = require('kth-node-server')
    // Load .env file in development mode
    const nodeEnv = process.env.NODE_ENV && process.env.NODE_ENV.toLowerCase()
    if (nodeEnv === 'development' || nodeEnv === 'dev' || !nodeEnv) {
      require('dotenv').config()
    }
    // Now read the server config
    const config = require('./init/configuration').server
    • make sure configuration/index.js has the following export:
    module.exports = require('./configuration')

    The following steps only for frontend

    • Add endpoint .../browserConfig to staticFiles.js (earlier name: routing.js)
    const paths = require('../routing/paths')
    const browserConfig = require('../configuration').browser
    const browserConfigHandler = require('kth-node-configuration').getHandler(browserConfig, paths)
    
    ...
    
    // Expose browser configurations
    server.use(config.proxyPrefixPath.uri + '/static/browserConfig', browserConfigHandler)
    • add a line of code to load handlebars-helpers in server.js
    // Register handlebar helpers
    require('./views/helpers')
    • Remove the handlebars helper if you have one
      <<globalSettingsForBrowserJS>>
    • remove /buildConfig.js

    • remove npm script "buildConfig" and also remove call to it from "postinstall"-hook

    • Change config imports in js-files

      	var config = require('config') => var config = { config: window.config, paths: window.paths }
      
    • include config in head, should look like this

    {{prefixScript '/static/js/vendor.js' 'head-scripts'}}
    {{prefixScript '/static/browserConfig' 'head-scripts'}}

    TODO

    TODO - add test for decodeUri.js

    TODO - add test for utils.js

    TODO - add test for unpackLDAPConfig.js

    TODO - add test for generateConfig.js

    TODO - add test for getHandler.js

    DONE

    DONE - add test for unpackNodeApiConfig.js

    DONE - add test for unpackMongodbConfig.js

    DONE - add test for unpackRedisConfig.js

    Install

    npm i kth-node-configuration

    DownloadsWeekly Downloads

    43

    Version

    2.0.12

    License

    none

    Unpacked Size

    48.4 kB

    Total Files

    37

    Last publish

    Collaborators

    • kthwebmaster
    • wkchung
    • exacs
    • ssundkvist
    • kth-ci
    • emilstenberg