Edit this page

Web Server Options

The following options control the configuration of your web server and the express app:

env

The environment setting to use. The keys development and production are supported, and this will have an impact on things like caching compiled templates. Defaults to process.env.NODE_ENV || "development".

You should really set this to production for your production servers using the NODE_ENV environment variable. Several other modules expect this convention also.

port

The port to listen for request on. Defaults to process.env.PORT || 3000

host

The ip address to listen for request on. Defaults to process.env.IP || '127.0.0.1'

port must be set (either by option or env variable) or the host option will be ignored.

views

The path to your application's view templates. This is required for using the keystone.View Class, and will also be set on the express app.

If you're following the recommended project structure, this should be set to "/templates/views".

view engine

The template engine to use by default. Any engine with express support should work. You will need to install any view engine you intend to use in your project

This option is set on the express app (see docs here).

custom engine

If you want to use a custom template engine, set this option to the function that should be used to process your templates.

See Below for an example of how to use the Swig template engine.

view cache

This option is passed through to Express, and controls whether compiled view templates are cached between requests. It defaults to true in production, or false otherwise so there is rarely any reason to set it explicitly.

locals

The default local variables to pass to your view templates. Routes can extend or change local variables by modifying res.locals.

static

One or more paths to your application's static files. Setting this will include the serve-static middleware.

If you're following the recommended project structure, this should be set to 'public'.

static options

Optional config options that will be passed to the serve-static middleware (see docs here).

less

If you want Keystone to automatically compile .less files into .css files, set this value to the same path as the static option.

When this option is set, any requests to a .css or .min.css file will first check for a .less file with the same name, and if one is found, the css file will be generated.

less options

Optional config options that will be passed to the less middleware; see github.com/emberfeather/less.js-middleware for more information.

sass

If you want Keystone to automatically compile .sass files into .css files, set this value to the same path as the static option.

When this option is set, any requests to a .css or .min.css file will first check for a .sass file with the same name, and if one is found, the css file will be generated.

Note that enabling this option requires you to have specified the node-sass package as a dependency in your project's package.json file; it is not automatically included with Keystone.

sass options

Optional config options that will be passed to the sass middleware; see github.com/sass/node-sass for more information.

favicon

The path to your application's favicon. Setting this will include the serve-favicon middleware. Should be relative to your project's root. If you're following the recommended project structure, this should be set to "/public/favicon.ico".

compress

Set this to true to enable HTTP compression. This will include the compression middleware (see docs here).

logger

Set this to include the morgan middleware. The value will be passed to the middleware initialisation (see docs here). Set this to false to disable logging altogether. Defaults to :method :url :status :response-time ms.

logger options

Optional config options that will be passed to the morgan middleware; see github.com/expressjs/morgan for more information.

trust proxy

Set this to enable processing of the HTTP request X-Forwarded-For header. Extracted IP addresses will be available as the array req.ips (see docs here).

Exposes onHttpServerCreated event

keystone.start({
  onHttpServerCreated: function() {
    var server = keystone.httpServer;
  }
});

HTTPS Web Server Options

There are two ways to implement HTTPS for your KeystoneJS application: either use a web server (e.g. NGINX) or PAAS (e.g. Heroku) that handles it for you, or set the following options to use the https server provided by node.js.

ssl

Whether to start the SSL Server. Defaults to false.

When set to true, both http and https servers will be started. If ssl key or ssl cert are invalid, just the http server will be started.

When set to "only", only the https server will be started. If ssl key or ssl cert are invalid, KeystoneJS will not start.

When set to 'force', there will be the same result as if 'true' was given except all requests to http will be redirected to https

ssl key

The path to your SSL Key. Should be either absolute or relative to process.cwd() (which is usually your project root).

ssl cert

The path to your SSL Certificate. Should be either absolute or relative to process.cwd() (which is usually your project root).

ssl ca

The path to your SSL CA Bundle. Should be either absolute or relative to process.cwd() (which is usually your project root).

ssl port

The port to start the SSL Server on. Defaults to 3001.

ssl public port

The public-facing port to send https requests to (Eg: for https redirects from http). Defaults to the value of the ssl port option.

ssl host

The ip address to listen for request on. Defaults to process.env.SSL_IP or the value of the host option.

letsencrypt

A configuration object used with letsencrypt-express to configure automatic SSL certificate registration (properties of this object can be found below).

letsencrypt.email

The email address to register as an admin email with letsencrypt. (Corresponds to the letsencrypt-express email property).

letsencrypt.domains

The domain(s) to register under the letsencrypt certificate. (Corresponds to the letsencrypt-express approveDomains property).

letsencrypt.register

Whether to automatically register/ renew the letsencrypt certificate.

letsencrypt.tos

Whether or not you agree to the Terms of Service. (Corresponds to the letsencrypt-express agreeTos attribute).

letsencrypt.production

Whether or not to use the letsencrypt production server to issue the certificate (versus using the staging server). To avoid hitting rate limits, set the value to false during setup to use the staging server.

Exposes onHttpsServerCreated event during keystone.start()

WARNING: If you intend to enable SSL on your KeystoneJS app, make sure you're using Node.js 0.10.33 or newer. Node versions prior to 0.10.33 are susceptible to the POODLE (Padding Oracle On Downgraded Legacy Encryption) vulnerability, a man-in-the-middle attack that targets SSLv3 (see CVE-2014-3566). As of Node version 0.10.33, the SSLv2 and SSLv3 protocols are disabled by default. For more information see the release notes for Node v0.10.33 (Stable).

Unix Socket Web Server Option

Express will listen to a unix socket for connections

unix socket

Path to a writable unix socket. Should be either absolute or relative to process.cwd() (which is usually your project root). File will be removed first if present.

When set http and https servers are ignored.

Exposes onSocketServerCreated event during keystone.start()