Edit Page

Miscellaneous (sails.config.*)

For a conceptual overview of configuration in Sails, see http://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 to a PaaS like Heroku, Azure App Service, or Deis, you may not need to configure sails.config.port, since in most cases it is 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.proxyHost and sails.config.proxyPort

If your site will ultimately be served by a proxy, you may want to set proxyHost to ensure that calls to sails.getBaseurl() return the expected host. For example, if you deploy a Sails app on Modulus.io, the ultimate URL for your site will be something like http://mysite-12345.onmodulus.net. If you were to use sails.getBaseurl() to construct a URL in your app code, however, it would return something like http://localhost:8080. Using proxyHost and proxyPort allow you to specify the host name and port of the proxy server that will be serving your app. This ensure that any links created using sails.getBaseurl() are correct.

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 to "production", Sails automatically sets sails.config.environment to "production" too. In fact, the reccommended way of switching to production mode is by _setting the NODEENV environment variable to "production". This is usually a better idea than configuring sails.config.environment manually, since the NODE_ENV environment variable is relied upon by some of Sails' dependencies, and automatically set by most Sails/Node.js hosting services.

Prior to Sails v1.0, the opposite was also true (Sails set the NODE_ENV environment variable to "production" automatically when lifting with sails.config.environment set to "production). In Sails v1.0, that is changing to provide better support for custom staging and sandbox environments.

For more background on configuring your Sails app for production, see Concepts > Deployment.

sails.config.hookTimeout

Set a global timeout for Sails hooks, in milliseconds. Sails will give up trying to lift if any hook takes longer than this to load. Defaults to 20000.

The most common use for 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.keepResponseErrors

By default, convenience functions badRequest, forbidden, notFound, and serverError will clear the response body when the environment is "production". This behavior may be undesirable in certain cases, such as exposing underlying Waterline validation errors to clients while responding through badRequest.

Set keepResponseErrors to true to ensure Sails preserves the response body for these functions.

The default behavior of responses will be changing a bit in Sails v1.0.

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 configuring SSL settings in once place: sails.config.ssl.

SSL and Load Balancers

The sails.config.ssl setting is only relevant if you want your Sails process to manage SSL. This isn't always true. For example, if you plan for your Sails app to get more and more traffic, it will need to scale to multiple servers, which means you'll need 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 actually won't need to use the sails.config.ssl setting 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 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'))
}

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-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Sails logo
  • Home
  • Get started
  • Support
  • Documentation
  • Documentation

For a better experience on sailsjs.com, update your browser.

Documentation

Reference Concepts App structure | Upgrading Contribution guide | Tutorials More

Reference

  • Application
    • Events
    • Lifecycle
    • sails.getRouteFor()
    • sails.getUrlFor()
    • sails.lift()
    • sails.load()
    • sails.log()
    • sails.lower()
    • sails.request()
    • sails.getBaseUrl()
  • Blueprint API
    • add to
    • create
    • destroy
    • find one
    • find where
    • populate where
    • remove from
    • update
  • Command Line Interface
    • sails console
    • sails debug
    • sails generate
    • sails lift
    • sails new
    • sails version
  • Configuration
    • sails.config.*
    • sails.config.blueprints
    • sails.config.bootstrap()
    • sails.config.connections
    • sails.config.cors
    • sails.config.csrf
    • sails.config.globals
    • sails.config.http
    • sails.config.i18n
    • sails.config.log
    • sails.config.models
    • sails.config.policies
    • sails.config.routes
    • sails.config.session
    • sails.config.sockets
    • sails.config.views
  • Request (`req`)
    • req.accepted
    • req.acceptedCharsets
    • req.acceptedLanguages
    • req.body
    • req.cookies
    • req.fresh
    • req.headers
    • req.host
    • req.ip
    • req.ips
    • req.isSocket
    • req.method
    • req.options
      • req.options.values
      • req.options.where
    • 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.acceptsCharset()
    • req.acceptsLanguage()
    • req.allParams()
    • req.file()
    • req.get()
    • req.is()
    • req.param()
  • Response (`res`)
    • res.attachment()
    • res.badRequest()
    • res.clearCookie()
    • res.cookie()
    • res.created()
    • res.forbidden()
    • res.get()
    • res.json()
    • res.jsonp()
    • res.location()
    • res.negotiate()
    • res.notFound()
    • res.ok()
    • res.redirect()
    • res.send()
    • res.serverError()
    • res.set()
    • res.status()
    • res.type()
    • res.view()
  • Waterline (ORM)
    • Models
      • .count()
      • .create()
      • .destroy()
      • .find()
      • .findOne()
      • .findOrCreate()
      • .native()
      • .query()
      • .stream()
      • .update()
    • Populated Values
      • .add()
      • .remove()
    • Queries
      • .exec()
      • .limit()
      • .populate()
      • .skip()
      • .sort()
      • .where()
    • Records
      • .save()
      • .toJSON()
      • .toObject()
  • WebSockets
    • Resourceful PubSub
      • .message()
      • .publishAdd()
      • .publishCreate()
      • .publishDestroy()
      • .publishRemove()
      • .publishUpdate()
      • .subscribe()
      • .unsubscribe()
      • .unwatch()
      • .watch()
      • .subscribers()
    • sails.sockets
      • .addRoomMembersToRooms()
      • .blast()
      • .broadcast()
      • .getId()
      • .join()
      • .leave()
      • .leaveAll()
      • .removeRoomMembersFromRooms()
      • sails.sockets.emit()
      • sails.sockets.id()
      • sails.sockets.rooms()
      • sails.sockets.socketRooms()
      • sails.sockets.subscribers()
    • Socket Client
      • io.sails
      • io.socket
      • SailsSocket
        • Methods
        • Properties
      • io.socket.delete()
      • io.socket.get()
      • io.socket.off()
      • io.socket.on()
      • io.socket.post()
      • io.socket.put()
      • io.socket.request()

Built with Love

The Sails framework is maintained by a web & mobile studio 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!

Sails:
  • What is Sails?
  • Treeline IDE
  • Contribute
  • Logos/artwork
About:
  • The Sails Company
  • Security
  • News
  • Legal
Help:
  • Get started
  • Documentation
  • Docs
  • Enterprise
  • Hire us

© 2012-2018 The Sails Company. 
The Sails framework is free and open-source under the MIT License.