Configuration

Overview

While Sails dutifully adheres to the philosophy of convention-over-configuration, it is important to understand how to customize those handy defaults from time to time. For almost every convention in Sails, there is an accompanying set of configuration options that allow you to adjust or override things to fit your needs.

Here looking for a particular setting? Head over to Reference > Configuration to see a complete guide to all configuration options available in Sails.

Sails apps can be configured programmatically, by specifying environment variables or command-line arguments, by changing the local or global .sailsrc files, or (most commonly) using the boilerplate configuration files conventionally located in the config/ folder of new projects. The authoritative, merged-together configuration used in your app is available at runtime on the sails global as sails.config.

Standard configuration files (config/*)

A number of configuration files are generated in new Sails apps by default. These boilerplate files include a number of inline comments, which are designed to provide a quick, on-the-fly reference without having to jump back and forth between the docs and your text editor.

In most cases, the top-level keys on the sails.config object (e.g. sails.config.views) correspond to a particular configuration file (e.g. config/views.js) in your app; however configuration settings may be arranged however you like across the files in your config/ directory. The important part is the name (i.e. key) of the setting—not the file it came from.

For instance, let's say you add a new file, config/foo.js:

// config/foo.js
// The object below will be merged into `sails.config.blueprints`:
module.exports.blueprints = {
  shortcuts: false
};

For an exhaustive reference of individual configuration options, and the file they live in by default, check out the reference pages in this section, or take a look at "config/" in The Anatomy of a Sails App for a higher-level overview.

Environment-specific files (config/env/*)

Settings specified in the standard configuration files will generally be available in all environments (i.e. development, production, test, etc.). If you'd like to have some settings take effect only in certain environments, you can use the special environment-specific files and folders:

• Any files saved under the /config/env/<environment-name> folder will be loaded only when Sails is lifted in the <environment-name> environment. For example, files saved under config/env/production will only be loaded when Sails is lifted in production mode.
• Any files saved as config/env/<environment-name>.js will be loaded only when Sails is lifted in the <environment-name> environment, and will be merged on top of any settings loaded from the environment-specific subfolder. For example, settings in config/env/production.js will take precedence over those in the files in the config/env/production folder.

By default, your app runs in the "development" environment. The recommended approach for changing your app's environment is by using the NODE_ENV environment variable:

NODE_ENV=production node app.js

The production environment is special: depending on your configuration, it enables compression, caching, minification, etc.

Also note that if you are using config/local.js, the configuration exported in that file takes precedence over environment-specific configuration files.

The config/local.js file

You may use the config/local.js file to configure a Sails app for your local environment (your laptop, for example). The settings in this file take precedence over all other config files except .sailsrc. Since they're intended only for local use, they should not be put under version control (and are included in the default .gitignore file for that reason). Use local.js to store local database settings, change the port used when lifting an app on your computer, etc.

See Concepts > Configuration > The local.js file for more information.

Accessing sails.config in your app

The config object is available on the Sails app instance (sails). By default, this is exposed on the global scope during lift, and therefore available from anywhere in your app.

Example

// This example checks that, if we are in production mode, csrf is enabled.
// It throws an error and crashes the app otherwise.
if (sails.config.environment === 'production' && !sails.config.security.csrf) {
  throw new Error('STOP IMMEDIATELY ! CSRF should always be enabled in a production deployment!');
}

Setting sails.config values directly using environment variables

In addition to using configuration files, you can set individual configuration values on the command line when you lift Sails by prefixing the config key names with sails_, and separating nested key names with double underscores (__). Any environment variable formatted this way will be parsed as JSON (if possible). For example, you could do the following to set the allowed CORS origins (sails.config.security.cors.allowOrigins) to ["http://somedomain.com","https://anotherdomain.com:1337"] on the command line:

sails_security__cors__allowOrigins='["http://somedomain.com","https://anotherdomain.com:1337"]' sails console

Note the use of double quotes to indicate strings within the JSON-encoded value, and the single quotes surrounding the whole value so that it is passed correctly from to Sails from the console.

This value will be in effect only for the lifetime of this particular Sails instance, and will override any values in the configuration files.

Also note that configuration specified using environment variables does not automatically apply to Sails instances that are started programmatically.

There are a couple of special exceptions to the above rule: NODE_ENV and PORT.

• NODE_ENV is a convention for any Node.js app. When set to 'production', it sets sails.config.environment.
• Similarly, PORT is just another way to set sails.config.port. This is strictly for convenience and backwards compatibility.

Here's a relatively common example where you might use both of these environment variables at the same time:

PORT=443 NODE_ENV=production sails lift

When present in the current process environment, NODE_ENV and PORT will apply to any Sails app that is started via the command line or programmatically, unless explicitly overridden.

Environment variables are one of the most powerful ways to configure your Sails app. Since you can customize just about any setting (as long as it's JSON-serializable), this approach solves a number of problems, and is our core team's recommended strategy for production deployments. Here are a few:

• Using environment variables means you don't have to worry about checking in your production database credentials, API tokens, etc.
• This makes changing Postgresql hosts, Mailgun accounts, S3 credentials, and other maintenance straightforward, fast, and easy; plus you don't need to change any code or worry about merging in downstream commits from other people on your team
• Depending on your hosting situation, you may be able to manage your production configuration through a UI (most PaaS providers like Heroku or Modulus support this, as does Azure Cloud.)

Setting sails.config values using command line arguments

For situations where setting an environment variable on the command line may not be practical (such as some Windows systems), you can use regular command line arguments to set configuration options. To do so, specify the name of the option prefixed by two dashes (--), with nested key names separated by dots. Command line arguments are parsed using minimist, which does not parse JSON values like arrays or dictionaries, but will handle strings, numbers and booleans (using a special syntax). Some examples:

// Set the port to 1338
sails lift --port=1338

// Set a custom "email" value to "[email protected]":
sails lift --custom.email='[email protected]'

// Turn on CSRF support
sails lift --security.csrf

// Turn off CSRF support
sails lift --no-security.csrf

// This won't work; it'll just try to set the value to the string "[1,2,3]"
sails lift --custom.array='[1,2,3]'

Custom configuration

You can also leverage Sails's configuration loader to manage your own custom settings. See sails.config.custom for more information.

Configuring the command line interface

When it comes to configuration, most of the time you'll be focused on managing the runtime settings for a particular app: the port, database setup, and so forth. However it can also be useful to customize the Sails CLI itself; to simplify your workflow, reduce repetitive tasks, perform custom build automation, etc. Thankfully, Sails v0.10 added a powerful new tool to do just that.

The .sailsrc file is unique from other configuration sources in Sails in that it may also be used to configure the Sails CLI—either system-wide, for a group of directories, or only when you are cd'ed into a particular folder. The main reason to do this is to customize the generators that are used when sails generate and sails new are run, but it can also be useful to install your own custom generators or apply hard-coded config overrides.

And since Sails will look for the "nearest" .sailsrc in the ancestor directories of the current working directory, you can safely use this file to configure sensitive settings you can't check in to your cloud-hosted code repository (like your database password.) Just include a .sailsrc file in your "$HOME" directory. See the docs on .sailsrc files for more information.

Order of precedence for configuration

Depending on whether you're starting a Sails app from the command line using sails lift or node app.js, or programmatically using sails.lift() or sails.load(), Sails will draw its configuration from a number of sources, in a certain order.

Order of precedence when starting via sails lift or node app.js (in order from highest to lowest priority):

• command line options parsed by minimist; e.g. sails lift --custom.mailgun.apiToken='foo' becomes sails.config.custom.mailgun.apiToken
• environment variables prefixed with sails_, and using double underlines to indicate dots; e.g.: sails_port=1492 sails lift (A few more examples)
• a .sailsrc file in your app's directory, or the first found looking in ../, ../../ etc.
• a global .sailsrc file in your home folder (e.g. ~/.sailsrc).
• any existing config/local.js file in your app
• any existing config/env/* files in your app that match the name of your current NODE_ENV environment (defaulting to development)
• any other files in your app's config/ directory (if one exists)

Order of precedence when starting programmatically (in order from highest to lowest priority):

• an optional dictionary ({}) of configuration overrides passed in as the first argument to .lift() or .load()
• any existing config/local.js file in your app
• any existing config/env/* files in your app that match the name of your current NODE_ENV environment (defaulting to development)
• any other files in your app's config/ directory (if one exists)

Notes

The built-in meaning of the settings in sails.config are, in some cases, only interpreted by Sails during the "lift" process. In other words, changing some options at runtime will have no effect. To change the port your app is running on, for instance, you can't just change sails.config.port—you'll need to change or override the setting in a configuration file or as a command line argument, etc., then restart the server.