Quickstart: Configuration

Brian edited this page Sep 3, 2016 · 5 revisions

In order to ensure that information is accurate, the system of record will always be the code level documentation in the /include/config.js file located here. While we want to insure that information about configuration is easy to find we would prefer it to be accurate. When in doubt check the source code documentation. Now, on to the part that matters.

The config.js file allows you to modify the core application settings for PencilBlue. Anything that is set in the core config file, located at /include/config.js, can be overwritten.

Creating the config.js File

Note: if you installed PencilBlue via pencilblue-cli, your config.js file will already be created and located in the root directory of your installation.

  1. Copy the supplied sample.config.js file and save it as config.js, either in the root directory of your installation or /etc/pencilblue/config.js. PencilBlue will load the file from either location.
  2. Open the config.js file and edit it to meet your desired configuration.

Common config.js Variables

Variable Name Description
siteName The name of your site that will display in page titles.
siteRoot The main URL of your site (e.g., http://pencilblue.org).
siteIP The IP address that the HTTP server(s) will bind to.
logging.level The amount of console output PencilBlue will generate (error, warn, info, debug, silly).
db The database settings, including type, server URLs, database name, and the write concern. This doesn't need to be changed on localhost installations.
cache Turns on and off the cache and sets whether Redis or FakeRedis is used.
settings Whether to cache the site's settings in memory or cache.
templates Whether to cache the site's HTML templates in memory or an actual cache.

Other Variables

Any other variable in the config object file at /include/config.js can be overridden by including it in the config.js file.

Notes About the Default Configuration

The out of the box configuration and sample configuration is meant only for local deployments. It allows users to quickly get PencilBlue running. Production configurations can be optimized based on your environment and available technologies to allow for horizontal scale.

Getting Ready for Production

Node.js forces developers to think about scale early because it does not automatically scale across all available cores of the server. In order to address this issue PencilBlue leverages the cluster module. When configured to do so, PencilBlue will start a master process and spawn a worker for each available core. This provides the ability to utilize all available server resources if needed.

The scenario described above means that each PencilBlue process that is started must be stateless as soon as we leverage more than 1 core. In order to do this we now require another dependency to handle 3 critical PencilBlue services:

  • Sessions - The ability to authenticate a user and keep stateful details about them as they interact with the site
  • Media Service - The ability to store files and provide access to them from any PencilBlue instance.
  • Service Registry - The ability for each PencilBlue instance to make itself known to each of the other instances.
  • Command Service - The ability for each PencilBlue instance to communicate with another instance.

The last 3 mentioned services are a bit more obtuse so we'll elaborate. The media service, out of the box, persists uploaded media to MongoDB's Grid FS. This works well for small files (documents, small images, etc). However, as soon as the files grow large in number and/or size it is time to consider other storage options.

The service registry comes in handy to track the health of the system and ensure each PB process is in sync. Once logged into the admin screen a table is shown that lists the PencilBlue process and few other details about each of them. This allows for site administrators to quickly gather details in the event that a process goes down or gets out of sync due to a fatal error. The registry also provides a listing of who is out there in the cluster.

The command service is built on top of the service registry. The command service provides the ability to send a messages back and forth between 1 or more PencilBlue processes. The best example of usage is our plugin framework. When a plugin is installed or uninstalled each instance in the cluster must sync up. The command services allows a single instance to get a listing of all instances via the service registry and then send a command to each one through the command service to perform the designated action.

We explain the above in order to provide an understanding for why other technologies become necessary for production deployments. For each of the 4 services mentioned above PencilBlue comes with multiple providers in order to support as many configurations as possible. In addition, the plugin framework allows developers to build their own implementations of these services should the out of the box options not fit their needs. In some cases we have already done that. Below we have outlined the options available for each service.

Current as of 09/03/2016

Media Service:

  • File System - single server only
  • Mongo GridFS (default)
  • Dropbox (plugin) - Dropbox v1 API is now deprecated
  • S3 (plugin)

Session Storage:

  • Mongo (default)
  • Redis - recommended for production deployments for speed
  • Memory (via FakeRedis module, only supports single process)

Service Registry:

  • Mongo (default)
  • Redis - recommended for production deployments due to Mongo's 60min document TTL
  • Memory (via FakeRedis module, only supports single instance)


  • Redis (default & preferred)
  • Mongo (not recommended for large scale use)
  • Memory (via FakeRedis module, only supports single instance)

Cached Settings, Templates and Objects

There are a few items that can be cached for fast lookup in PencilBlue. For each of these items different caching layers can be configured (Redis, in-memory). There are cases when in-memory is appropriate and some when it is not.

Settings should only use in-memory caching if it is a part of a small cluster. The in-memory settings leverage PencilBlue's command service to notify each member of the cluster of changes to settings. Large clusters could suffer performance loss due to increased traffic and the delay in ensuring that each member is updated. As a fallback, the settings values will timeout ensuring that the cluster stays in sync. It is recommended that production multi-instance or multi-server clusters use an actual instance of Redis to provide fast access to these settings. If Redis is not an option for your large cluster you should turn off both in-memory and cache properties for settings in your configuration:

//configuration used when no cache is available and running in multi-server or multi-instance environment
  settings: {
    use_memory: false,
    use_cache: false

Plugin settings behave the same as regular system settings and therefore the recommendations are the same.

//configuration used when a Redis instance is available in any environment
  plugins: {
    use_memory: false,
    use_cache: true

Templates are a bit different. Since they don't change once deployed it is ok to turn in-memory caching on. This means that the templates will only be compiled once and stored in-memory for the lifetime of the process. If you are worried about memory consumption it is possible to place the compiled templates into the cache to provide fast access. The recommended configuration for templates is below and is safe for multi-server deployments:

//recommended configuration to be used any environment
  templates: {
    use_memory: true,
    use_cache: false

Working with the Cache

In order to make development easier PencilBlue provides a dependency on the ```fakeredis`` module. It allows for devs to run locally without the need for an instance of Redis up and running. It is also beneficial when a clean slate is needed after each code change. The restart would wipe out the in-memory cache.

One Config.js to Rule Them All

Since the config.js file is simply another module it is possible to create one that will export configuration that is different depending on your environment. For example, when deploying to elastic cloud environments certain details such as IP address and cache details are not known ahead of time. Static configurations would be impractical and force developers to place sensitive information such as DB credentials directly into committed configuration files. The solution is a config.js file that reads environment variables or other available resources to build out a configuration. For details about how to build out configurations for specific cloud providers see the Cloud Hosting section of our wiki.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.