Edit this page

Part 1: Initial Setup


If you want to jump right in to a working Keystone codebase, check out the Quick Start guide which walks you through using our generator to get a Keystone codebase up and running quickly.

This Setting Up tutorial will walk you through setting up a project from scratch, including introducing and configuring the core parts of Keystone.

This guide assumes you are familiar with using npm to install packages and JavaScript as a programming language.

We're going to be tackling setting up from scratch in four parts:

  • Part 1: Initial Setup (the page you are reading) starts with installation and setting up a keystone.js file to launch your application.

  • Part 2: Data Model Setup walks you through building your first data model.

  • Part 3: Routing introduces setting up routes with Keystone to serve website pages.

  • Part 4: Adding data from a form demonstrates how to create a POST endpoint for submitting data.

Before getting started, make sure you have Node.js and MongoDB installed.


Start by creating a new directory and then from within it run npm init. Follow the prompts to create a default package.json.

Next, install Keystone with npm install --save keystone.

At this point, you should have a node_modules directory and Keystone should have been added to the package.json.

Initial Setup

Create a new file, keystone.js, and you'll be ready to start configuring Keystone.

keystone.js file is the launch file for Keystone: it defines general configuration options, initialises Keystone, and starts your application server.

The minimum file we need to start Keystone running is:

var keystone = require('keystone');

  'cookie secret': 'secure string goes here',


Your keystone.js needs to require keystone and then run the keystone.init() function to set up Keystone's initial values.

In this example we are only providing a cookie secret. Technically this is the only non-default option that is required to launch Keystone, however as you complete this tutorial you will be adding more options.

Finally, we call keystone.start(), which kicks off the Keystone app.

You can now check this runs. Run node keystone.js and you should be greeted with:

KeystoneJS v4.0.0 started:
Keystone is ready on

You should get a 404 page. That's expected since there are no pages set up yet.

Next Steps

This tutorial continues in Part 2: Data Model Setup, which walks you through setting up your first data model.

Learn more about: