Edit Page

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:

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 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:

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 "foo@bar.com":
sails lift --custom.email='foo@bar.com'

// 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):
#
Order of precedence when starting programmatically (in order from highest to lowest priority):
#

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.

Next up: Policies

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Concepts