How to Install Keystone

Keystone is the easiest way to build database-driven websites, applications and APIs in Node.js.

This application provides multiple awesome features. It is used for creation of dynamic web sites or applications with well-structured routes, templates and models. Keystone auto-creates a beautiful Admin UI, based on the database models you define, and enhances models with additional field types and functionality. And integration with different services provides even more features:

Integration with Cloudinary for image uploading, storage and resizing
Integration with Mandrill for sending emails easily
Integration with Google Places for clever location fields
Integration with Embedly for powerful video and rich media embedding tools

In this tutorial, we’ll describe how to easily host your Keystone project within the platform.

Create Environment

1. Log in to the platform and click the New Environment button in the upper left corner of the dashboard.

2. In the opened frame switch to the Node.js tab and choose NodeJS as your application server and MongoDB as a NoSQL database. Use the cloudlet sliders to allocate the required amount of resources for these nodes. Then type your environment name (e.g. keystone) and click the Create button.

envirronment topology wizard

Your environment will be created in a few minutes.

Create Database

Create a new database for your Keystone application.

1. Click the WebSSH icon next to the MongoDB instance and issue commands in the open terminal.

2. Log in the mongo database with user credentials you got upon installation:

1
mongo -u admin -p CYAacv61166 admin

MongoDB log in

3. The next command creates the database, e.g. keystonedb.

1
use keystonedb

4. Add a user for the newly created database with username, password, and role:

1
db.createUser({ user: "keystoneuser", pwd: "keystonepassword", roles: ["readWrite","dbAdmin"] })

MongoDB create user

Now you have an empty DB and credentials to access it from your Keystone application.

Run Keystone

1. To start the application you need to access your environment via SSH protocol.

2. The easiest way to get started with Keystone is to use the Yeoman generator. Type the following commands in your terminal in order to install it:

1
2
sudo npm install -g yo
sudo npm install -g generator-keystone

3. Once the installation is finished, let’s create a new directory for your project, for example, keystone-project in the ROOT folder and navigate inside it.

1
2
3
cd $ROOT_DIR
mkdir keystone-project
cd keystone-project

create Keystone project directory

4. Now it’s time to create a new project with the help of the embedded wizard. Type the next command:

1
yo keystone

Answer the appeared questions in order to include the preferred modules to your site and configure it:

configure Keystone installation

Wait until all the necessary packages are installed and your project is ready.

5. Before you run your application, it should be connected to the previously created database. Therefore, open the .env file in the keystone-project/my-site folder using a built-in editor in Configuration File Manager.

adjust .env configuration file

Add the following line to it:

1
MONGO_URI=mongodb://{user}:{password}@{database_URL}:27017/{database_name}

Here should be substituted:

{user} with keystonedb database username keystoneuser in our example
{password} with respective password keystonepassword as for keystoneuser
{database_URL} with the link to your DB server that can be found in the respective email
{database_name} - with the name of the database you’ve created earlier the keystonedb as for our example.

So, the final connection string may look like as follows:

1
MONGO_URI=mongodb://kystoneuser:keystonepassword@node268626-keystone.vip.jelastic.cloud:27017/keystonedb

Note: If you’ve added some modules to your site (like image gallery, etc.) .env file can contain some additional connection strings. DO NOT delete these settings, just add the specified line below them.

add Mongo URI

6. Now we are about to start as the main website of our Keystone application instead of the default one that comes with the platform Node.js certified template. To do that you have to replace the content of the ROOT directory with the content of our keystone project ROOT/keystone-project/my-site. Issue the following commands in the terminal at the application server:

1
2
3
4
cd $ROOT_DIR  - goes to the /home/jelastic/ROOT directory
ls | grep -v keystone-project | xargs rm -rfv -  removes all of the files from the ROOT
mv keystone-project/my-site/{.[!.],}* .  - reallocates all content from keystone-project/my-site directory to the ROOT
ln -s keystone.js server.js - creates a symbolic link server.js to the keystone.js, since nodejs daemon runs servers.js by default

In order to run keystone on the port 8080 open keystone.js file in the dashboard editor and add the following line as follows: