Miscellaneous (sails.config.*)
For a conceptual overview of configuration in Sails, see https://sailsjs.com/documentation/concepts/Configuration.
This page is a quick reference of assorted configuration topics that don't fit elsewhere, namely top-level properties on the sails.config object. Many of these properties are best set on a per-environment basis, or in your config/local.js. To set them globally for your app, create a new file in the config folder (e.g. config/misc.js) and add them there.
sails.config.port
The port setting determines which TCP port your Sails app will use to listen for incoming requests. Ports are a transport-layer concept designed to allow many different networking applications to run at the same time on a single computer.
By default, if it’s set, Sails uses the port configured in your app (sails.config.port). If not, it checks to see if the PORT environment variable is set, and uses that if possible. Otherwise it falls back to port 1337.
In production, you will probably want Sails to listen on port 80 (or 443, if you have an SSL certificate and are serving your site via
https://), but depending on where your app is deployed, you may or may not need to actually modify this setting. For example, if you are deploying behind a proxy, or to a PaaS like Heroku, Azure App Service, or Deis, you probably won't need to configuresails.config.port, since in most cases that's handled automatically. For more guidance and tips related to deploying, scaling, and maintaining Sails in production, see Concepts > Deployment.
sails.config.explicitHost
By default, Sails will assume localhost as the host that will be listening for incoming requests. This will work in the majority of hosting environments you encounter, but in some cases (OpenShift being one example) you'll need to explicitly declare the host name of your Sails app. Setting explicitHost tells Sails to listen for requests on that host instead of localhost.
sails.config.environment
The runtime “environment” of your Sails app is usually either development or production.
In development, your Sails app will go out of its way to help you (for instance you will receive more descriptive error and debugging output).
In production, Sails configures itself (and its dependencies) to optimize performance. You should always put your app in production mode before you deploy it to a server; this helps ensure that your Sails app remains stable, performant, and scalable.
Using the "production" environment
By default, Sails determines its environment using the NODE_ENV environment variable. If NODE_ENV is not set, Sails will look to see if you provided a sails.config.environment setting, and use it if possible. Otherwise, it runs in the development environment.
When you lift your app with the NODE_ENV environment variable set to production, Sails automatically sets sails.config.environment to production too. This is the recommended way of switching to production mode. We don't usually recommend configuring sails.config.environment manually, since some of Sails’ dependencies rely on the NODE_ENV environment variable, and it is automatically set by most Sails/Node.js hosting services.
If you attempt to lift a Sails app in the production environment without setting NODE_ENV to production (for example, by running sails lift --prod), Sails automatically sets NODE_ENV to production for you. If you attempt to lift a Sails app in production while NODE_ENV is set to a different value (for example NODE_ENV=development sails lift --prod), the app fails to start.
For more background on configuring your Sails app for production, see Concepts > Deployment.
Note that it is perfectly valid to set sails.config.environment to something else entirely, like "staging", while still setting NODE_ENV=production. This causes Sails to load a different environment-specific configuration file (e.g. config/env/staging.js) and Grunt task (e.g. tasks/register/staging.js), while still otherwise acting like it's in production.
sails.config.hookTimeout
A time limit, in milliseconds, imposed on all hooks in your app. Sails will give up if any hook takes longer than this to load. Defaults to 20000 (20 seconds).
The most common reason to change this setting is to tolerate slow production Grunt tasks. For example, if your app is using uglify, and you have lots and lots of client-side JavaScript files in your assets folder, then you might need Sails to wait longer than 20 seconds to compile all of those client-side assets. For more tips about the production asset pipeline, see Concepts > Deployment.
sails.config.ssl
SSL/TLS (transport-layer security) is critical for preventing potential man-in-the-middle attacks. Without a protocol like SSL/TLS, web basics like securely transmitting login credentials and credit card numbers would be much more complicated and troublesome. SSL/TLS is not only important for HTTP requests (https://), it's also necessary for WebSockets (over wss://). Fortunately, you only need to worry about configuring SSL settings in one place: sails.config.ssl.
SSL and load balancers
The
sails.config.sslsetting is only relevant if you want your Sails process to manage SSL. This isn't always the case. For example, if you expect your Sails app to get more traffic over time, it will need to scale to multiple servers, necessitating a load balancer. Most of the time, for performance and simplicity, it is a good idea to terminate SSL at your load balancer. If you do that, then since SSL/TLS will have already been dealt with before packets reach your Sails app, you won't need to use thesails.config.sslsetting at all. (This is also true if you're using a PaaS like Heroku, or almost any other host with a built-in load balancer.)If you're satisfied that this configuration setting applies to your app, then please continue below for more details.
Use sails.config.ssl to set up basic SSL server options, or to indicate that you will be specifying more advanced options in sails.config.http.serverOptions.
If you specify a dictionary, it should contain both key and cert keys, _or_ a pfx key. The presence of those options indicates to Sails that your app should be lifted with an HTTPS server. If your app requires a more complex SSL setup (for example by using SNICallback), set sails.config.ssl to true and specify your advanced options in sails.config.http.serverOptions.
SSL configuration example
For this example, we'll assume you created a folder in your project, config/ssl/ and dumped your certificate/key files inside. Then, in one of your config files, include the following:
// Assuming this is in `config/env/production.js`, and your folder of SSL cert/key files is in `config/ssl/`:
ssl: {
ca: require('fs').readFileSync(require('path').resolve(__dirname,'../ssl/my-gd-bundle.crt')),
key: require('fs').readFileSync(require('path').resolve(__dirname,'../ssl/my-ssl.key')),
cert: require('fs').readFileSync(require('path').resolve(__dirname,'../ssl/my-ssl.crt'))
}
For a better experience on sailsjs.com, update your browser.
Reference
- Application
- Blueprint API
- Command-line interface
-
Configuration
- sails.config.*
- sails.config.blueprints
- sails.config.bootstrap()
- sails.config.custom
- sails.config.datastores
- sails.config.globals
- sails.config.http
- sails.config.i18n
- sails.config.log
- sails.config.models
- sails.config.policies
- sails.config.routes
- sails.config.security
- sails.config.session
- sails.config.sockets
- sails.config.views
-
Request (`req`)
- req._startTime
- req.body
- req.cookies
- req.fresh
- req.headers
- req.hostname
- req.ip
- req.ips
- req.isSocket
- req.method
- req.options
- req.originalUrl
- req.params
- req.path
- req.protocol
- req.query
- req.secure
- req.signedCookies
- req.socket
- req.subdomains
- req.url
- req.wantsJSON
- req.xhr
- req.accepts()
- req.acceptsCharsets()
- req.acceptsLanguages()
- req.allParams()
- req.file()
- req.get()
- req.is()
- req.param()
- req.setLocale()
- req.setTimeout()
- req.host
- Response (`res`)
- Waterline (ORM)
- WebSockets
Reference
Built with Love
The Sails framework is built by a web & mobile shop in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!
© 2012-2024 The Sails Company.
The Sails framework is free and open-source under the MIT License.
Illustrations by Edamame.