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
.
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.
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:
/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.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.
config/local.js
fileYou 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.
sails.config
in your appThe 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.
// 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!');
}
sails.config
values directly using environment variablesIn 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
andPORT
.
NODE_ENV
is a convention for any Node.js app. When set to'production'
, it setssails.config.environment
.- Similarly,
PORT
is just another way to setsails.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
andPORT
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:
sails.config
values using command line argumentsFor 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]'
You can also leverage Sails's configuration loader to manage your own custom settings. See sails.config.custom for more information.
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.
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.
sails lift
or node app.js
(in order from highest to lowest priority):sails lift --custom.mailgun.apiToken='foo'
becomes sails.config.custom.mailgun.apiToken
sails_
, and using double underlines to indicate dots; e.g.: sails_port=1492 sails lift
(A few more examples).sailsrc
file in your app's directory, or the first found looking in ../
, ../../
etc..sailsrc
file in your home folder (e.g. ~/.sailsrc
).config/local.js
file in your appconfig/env/*
files in your app that match the name of your current NODE_ENV environment (defaulting to development
)config/
directory (if one exists){}
) of configuration overrides passed in as the first argument to .lift()
or .load()
config/local.js
file in your appconfig/env/*
files in your app that match the name of your current NODE_ENV environment (defaulting to development
)config/
directory (if one exists)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 changesails.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.