Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Deploying KeystoneJS to Heroku

Deploying a Keystone App to Heroku

Keystone comes completely set up to install on Heroku in a couple of steps.

1. Sign up for a Heroku account and install the Heroku Toolbelt.

Log in with it and you're ready to begin. Heroku uses git to deploy a new site, so with that in mind:

2. Create a new repository on Github and then clone it.

3. Run the Keystone Yeoman generator.

(if you don't have yeoman then npm install -g yo)

yo keystone

4. cd into your project’s root folder and run heroku create.

heroku create

Heroku will generate an app name for you (something like beautiful-island-4327) and set up a git remote called heroku to use for identification (for deployment, etc).


5. Rename if to something more useful.

heroku apps:rename your-app-name --app current-name-of-your-app

You should see something like this:


6. Add your new Heroku remotes.

heroku git:remote --app deploy-tester-4000

Now for some add-ons!

Firstly, you’ll need a database. There are a few provides you can choose from in Heroku’s add-ons directory. For the purpose of this walk-through we’ll be using Mongolab (gives you <= 512mb for free).

N.B: You'll have to set up billing to do this (it won't charge you; they just want a credit card on file)

7. Add Mongolab.

heroku addons:add mongolab:sandbox

You should see something like this:


N.B: You can point your Keystone site at any database provider by customising the MONGO_URI environment variable (make sure to remove the mongolab addon first!)

Secondly, let’s add a logging system. Again, there are a few to choose from but we'll be usinfg Papertrail. This gives you a nice web UI to your application logs (i.e. console.log()) and lets you set up alerts for errors, etc. The basic plan for papertrail is also free.

8. Add Papertrail. heroku addons:add papertrail:choklad

You should see something like this:


9. Finally, you'll want to set up a Cloudinary account. You can do this yourself (the dashboard gives you the ENV variable to set up) or you can add it as an add-on to your Heroku account like Mongolab and Papertrail - we recommend you do this manually as you'll probably want to use the account in development and staging as well, rather than having it tied to a single Heroku app.

  • Bonus: if you click through to the signup page from the Keystone docs you should get access to a special cheaper low-tier plan for Keystone users. Also free for light traffic though. *her

Ok, that’s the setup process over.

10. Once you've created your app and got the database (at least) configured, just commit all your code to git and run this command to make your site go live:

git push heroku master

Your site will now be hosted at

Log into your account to add a real domain for it, and then just point your DNS at Heroku and you're off.

You can also set up SSL and whatever else you need.

The only thing to be aware of is that Heroku doesn't keep any changes to the local file system so you can't keep user-uploaded images (etc) without putting them on a 3rd party site / service, hence the Cloudinary / Azure / S3 integration.

You're all set.

Make sure to check out Heroku’s getting started docs for Node.js if you hit any hurdles.

Copy link

ovbm commented Jan 14, 2017

Great step by step guide! Thanks a lot.

Copy link

GWSB commented Feb 24, 2017

I've followed this guide from start to finish,, as well as a few others, numerous times and always end up with the same results.

Is keystonejs just broken right now?

Here's my error log in heroku.

2017-02-24T04:59:02.316526+00:00 app[web.1]: at require (internal/module.js:20:19) 2017-02-24T04:59:02.316526+00:00 app[web.1]: at /app/node_modules/keystone/index.js:189:23 2017-02-24T04:59:02.316527+00:00 app[web.1]: at Array.forEach (native) 2017-02-24T04:59:02.316527+00:00 app[web.1]: at doImport (/app/node_modules/keystone/index.js:176:28) 2017-02-24T04:59:02.316528+00:00 app[web.1]: at Keystone.import (/app/node_modules/keystone/index.js:198:9) 2017-02-24T04:59:02.316529+00:00 app[web.1]: at Object.<anonymous> (/app/keystone.js:38:16) 2017-02-24T04:59:02.316529+00:00 app[web.1]: at Module._compile (module.js:570:32) 2017-02-24T04:59:02.404005+00:00 heroku[web.1]: Process exited with status 1 2017-02-24T04:59:02.413680+00:00 heroku[web.1]: State changed from starting to crashed 2017-02-24T04:59:05.674339+00:00 heroku[router]: at=error code=H10 desc="App crashed" method=GET path="/" request_id=7ba73edd-98a6-42ac-865a-2c19ed121d7c fwd="" dyno= connect= service= status=503 bytes= 2017-02-24T04:59:05.966987+00:00 heroku[router]: at=error code=H10 desc="App crashed" method=GET path="/favicon.ico" request_id=1bef14f1-58cd-4630-853d-2829831bdcf1 fwd="" dyno= connect= service= status=503 bytes=

Copy link

jppmo commented Apr 28, 2017

@GWSB bump

Copy link

dallen4 commented May 5, 2017

Are there best practices for deploying an app to an already existing heroku app?

Copy link

petyoMitkov commented Sep 24, 2017

Hi everyone, I have a big problem with deploy KeystoneJS app to Heroku.

Tried to add NODE_ENV =produnction , MONGODB_URI and include CLOUDINARY_URL in .env file.

In package.json I have "start": "node keystone.js"

In file keyston.js added:
keystone.set('cloudinary config', { cloud_name: 'name', api_key: 'key', api_secret: 'appsecret' });

Searching in the net and do not find solve of my problem. Tried with this steps above buy not work in my case.

Also used Heroku CLI and then tried with GitHub byt the result was the same.

On my site see “Application error” error H10

Please help

Copy link

elijah-io commented Nov 5, 2017

Check to make sure your .gitignore file isn't ignoring the .env file before deploying to server from your CLI.

Copy link

manojdcoder commented Dec 13, 2017

@elijahio Thanks, it worked for me.

Copy link

arash2060 commented Nov 19, 2018

@elijahio Thanks! I spent so many hours thinking the problem was with something else....

Copy link

edlongman commented Apr 25, 2019

From deploying this recently I discovered you also need to set a COOKIE_SECRET environment variable

Copy link

jpgringo commented Jun 7, 2019

Fwiw for anyone experiencing similar issues: I was just having a rotten time trying to get my KeystoneJS site to deploy to Heroku. I…

  • specified my node version
  • specified my npm version
    … and it still didn't work
  • deleted my node_modules directory
  • switched to Yarn and reinstalled node_modules with "yarn install"
    … and everything worked!
  • deleted the specified npm version and specified the yarn version instead (just to "dot the i's")
    … and no problems since.

The relevant top-level entry in package.json looks like:

    "node": "~10.15.3",
    "yarn": "~1.16.0"

Your specific versions for your project may of course vary, but the basic idea would hold, I think.

Also: KeystoneJS failed to launch until I specified the CLOUDINARY_URL and COOKIE_SECRET config vars in the Heroku dashboard for the app.

Copy link

jpgringo commented Jun 7, 2019

(I also notice that someone above suggested including a ".env" file in your repo… NEVER do that!! Use the Heroku config vars instead, or whatever method your deployment platform uses for exposing NodeJS ENV vars to the app. The whole point of those variables is that they are locally specified and do not 'travel' with the app.)

Copy link

vitalbone commented Jun 10, 2019

Apologies for not following up on any of the earlier comments! I've had my notifications for GitHub turned off until recently so I hadn't realised this note to myself had become a guide for others. Sounds like following @jpgringo's advice should get the job done for deploying a KeystoneJS v4 site. (He's also very correct about the .env file - don't commit it, please use the Heroku config vars).

On a semi-related note - KeystoneJS have recently released v5 and it's a beauty! Check it out!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment