← back to the blog

Building Keystone From Source

Posted in KeystoneJS

This article describes how to get the basic KeystoneJS engine up and running on a Digital Ocean Droplet running Ubuntu 16.04. Following these instructions will get you a minimally running KeystoneJS with a cloned repository that you can update through git, make changes, and subit pull requests with.


Be sure to start with part 2 as it has more up-to-date information.


These instrucitons document how to install the latest version of KeystoneJS from source using a Digital Ocean droplet running Ubuntu 16.04. If you use another host or operating system, you mileage may vary.



I wanted to create this list of instructions mostly for myself, but I also plan to post a link on the KeystoneJS mailing list. Getting a KeystoneJS installation to run successfully is one of the biggest hurdles for potential new developers. Even if you get the Keystone yeoman generator to work, it does not create a repository clone that you can update with git. The install described here is minimal. It does not include the Admin UI files that come with the yeoman generator. But you can copy the output files from the yeoman generator if you successfully get the Keystone core running using these instructions.

1. Create a new Digital Ocean Droplet with Ubuntu 16.04. It needs to be a $10 droplet at minimum with 1GB of ram. The $5 512MB RAM Droplet is not powerful enough to compile KeystoneJS.


2. Install Mongo DB by following this tutorial. No need to complete step 3, as MongoDB does not need to be accessible from the internet as we'll be interacting with it through KeystoneJS.


3. As root, install the following packages:

• apt-get install make

• apt-get install git

• apt-get install g++


4. As root, add a new user with sudo privledges.

• adduser trout

• adduser trout sudo

5. As root, install Node and NPM. You can refer to various methods described here

a. apt-get install -y nodejs-legacy

b. apt-get install -y npm

As of this writing, this installed node v4.2.6 and npm 3.5.2

6. Log in as your normal user. For this tutorial, I'll use the user 'trout'. From here, you should skip to step 11 and clone the repository containing the required libraries. For posterity, I've kept steps 7 through 10 to replicate the install from scratch as much as possible.


7. Install the yeoman generator:

a. Sudo npm install -g yo

It's important to run as sudo and use the -g option. Otherwise you won't be able to run the 'yo' command.


8. Install the express generator:

a. npm install generator-node-express


9. Create the directory that will contain the KeystoneJS system and cd into it. In this case, I'm calling the directory 'keystone-build'.

a. mkdir ~/keystone-build

b. cd ~/keystone-build


10. Inside the keystone-build directory, run 'yo node-express'. I used the following options. Ultimately though, none of them matter.

a. Project name: Keystone

b. Libraries: all

c. Editors: none

d. Browser: Chrome

e. Heroku: No

The code that represents the main file of your Keystone application is app.js.


11. Return to the parent 'keystone-build' directory. The following packages are needed by KeystoneJS but are not readily available in NPM, so I created a GitHub repository with the node_modules directory included. You can find it here. These libraries were copied from a working version of KeystoneJS.

a. serve-static

b. serve-favicon

c. body-parser

d. cookie-parser

e. multer

My GitHub repository captures all the work done between steps 7 through 11. It contains the above libraries and an app.js file for running Keystone. It will overwrite the keystone-build directory. The above libraries can also be extracted from the yoeman keystone generator output, even if it does not build a running version of KeystoneJS.

a. cd

b. git clone https://github.com/christroutner/keystone-build


12. Enter the node_modules directory and clone the KeystoneJS repository with this command:

a. cd ~/keystone-build/node_modules

b. rmdir keystone

c. git clone https://github.com/keystonejs/keystone


13. Run npm install inside the keystone directory:

a. cd ~/keystone-build/node_modules/keystone

b. npm install


14. Return to the parent 'keystone-build' directory. If you cloned the keystone-build repo, the app.js file will be ready to launch Keystone. This is a modified version of the code in the KeystoneJS Wiki.

a. node app.js