Running PencilBlue on Heroku and MongoHQ

Hosting your own, live version of our Node.js CMS platform for free

July 21, 2014
Update: After this article was released, MongoHQ changed their name to Compose.

With the rise of the cloud has come a whole new breed of hosting providers who offer free, development level hosting at no charge. While one would never want to run business level code on these services, they get the job done for low traffic, personal projects. These are definitely "freemium" services, designed to make it easier to pay to upgrade to a paid plan, instead of migrating to another service, but the price points are generally competitive.

Two of the most popular services for Node.js and MongoDB hosting are Heroku and MongoHQ, respectively. In this tutorial, you'll learn how to use these two services to host your PencilBlue site for free, on your own custom domain. Obviously, the first step will be signing up for these services.

1. Create a Heroku account and install the Heroku Toolbelt

Go to and register for a free account. Once you've registered, download and install the Heroku Toolbelt. The toolbelt will give you command line tools that will make it easier to deploy your code to Heroku servers.

2. Create a MongoHQ account and free database

Note: MongoHQ has an add-on for Heroku that allows you to tie your database directly to your application, but installing add-ons requires storing payment information with Heroku. Since our goal with this tutorial is hosting a website completely free, we'll create our database directly through MongoHQ.

Go to MongoHQ and register for a free account. After registration, you'll be taken to the dashboard screen, where you can click on the Add Database button. Select a free, 512MB sandbox database from the Add Database screen and give it a name.

From your new database's management screen, click the "add a database user" link. Fill in a username and password for the database user and click "Add user." Now you'll have credentials for PencilBlue to connect to your MongoHQ database and configure it for use. 

The MongoHQ dashboard for a new database
3. Clone the PencilBlue repository to your computer

Open a terminal, navigate to the directory you want the PencilBlue folder to be in and run:

git clone pencilblue
This will install the PencilBlue source code to your computer so you can edit it and push it up to Heroku. Note: you will not need to run an npm install call in this installation, because Heroku recognizes the package.json file on your first push and downloads the dependencies for you.

4. Prepare the PencilBlue setup for Heroku

After the repository is cloned, use the terminal to change your directory to the new folder and remove the .gitignore file, because we want to push all files to Heroku:

cd pencilblue
git rm .gitignore
The final modification to the source code will be creating a config.json file. Open up a text editor and create a duplicate of PencilBlue's sample.config.json file called config.json, then make the following modifications:

  • Delete the sitePort line. Heroku will set the site's port automatically.
  • Choose a unique name for your application and modify siteRoot to be "http://[app name]" and siteIP to be "[app name]"
  • From your MongoHQ database management screen, click on "connect directly to your database" and copy the Mongo URI code. In the config.json file, under db paste the copied code into the first element in the servers array then modify it to include your added database user and password. Update: use the authentication setting under db to pass the username and password for the database. Also, be sure to put a slash at the end of the mongodb:// url.
  • Change the name, under db to your database name
Here's an example of what your config.json file should now look like:

    "siteName": "PencilBlue Heroku and MongoHQ Demo",
    "siteRoot": "",
    "siteIP": "",
    "log_level": "info",
    "db": {
        "servers": [
        "name": "pbherokudemo",
        "authentication": {
            "un": "pbuser",
            "pw": "password",
        "writeConern": 1
    "cache": {
        "fake": true,
        "host": "localhost",
        "port": 6379
    "settings": {
        "use_memory": true,
        "use_cache": false
    "templates": {
        "use_memory": true,
        "use_cache": false
    "plugins": {
        "caching": {
            "use_memory": true,
            "use_cache": false
5. Create a Procfile

Create a file name Procfile in the PencilBlue root directory and add the following to it:

web: node pencilblue.js
This will tell Heroku what to run to start the PencilBlue application.

6. Commit the changes, create the heroku remote and push to it

From the terminal, commit your changes to the local git repository:

git add .
git commit -m "initial heroku setup"
Now use the Heroku Toolbelt to create the git remote and then push your code up to Heroku:

heroku create [app name]
git push heroku master
You might notice, at this point, that the terminal output is not that of a normal git push. That's because Heroku is pushing the source to one of their dynos, installing npm dependencies, and starting the application. Once that process is done you should be able to navigate to [app name] and see the PencilBlue setup screen. Note: because Heroku does not allow apps to have file write access, you won't be able to upload media. In keeping with the free theme, you can upload your photos to Imgur and link to them when creating media objects.


If [app name] throws an application error, then the first thing you'll want to do is check the logs:

heroku logs
Walk through the steps of this tutorial and see if you missed one (common mistakes I make include not removing sitePort from config.json and forgetting to change the database name). If the logs show an authentication error with MongoDB, recheck the credentials you added. If that doesn't work, follow the steps in this troubleshooting doc from MongoHQ.

7. Use your own domain (optional)

Go back to the Heroku website and access your application. Under Settings is a Domains section. Add your custom domain to the list and save.

Modify the siteRoot and siteIP fields in config.json to be your custom domain, then push the changes to Heroku like we did in step 6. Change your domain's DNS settings to have a CNAME record pointing to [app name] Your website should be up and running on the new URL.

The Heroku dashboard and application settings
Your new website

Now that you have a server up and running, you can continue to use it to test and develop with PencilBlue, or use it to run a low-level production website. But, if you want to increase the performance of your installation, both Heroku and MongoHQ offer upgrades on their free setup to make your existing website production worthy.

Heroku's free instances will go to sleep when not being hit, so they will be slow to respond when the first person goes to your website after a lull. To have the application always on, they offer one dyno at $0.05 per hour (~$36 per month) or two, load balanced dynos at $0.10 per hour (as of the writing of this article). Alternatively, services like Linode offer single CPU instances at $10 a month. So, if you know you're going to want production worthy performance, using non-free services from the start might save you money in the long run.

MongoHQ's free databases will always be up, but they're limited to 512MB. They offer production databases at $18 per month, per Gigabyte. It takes a lot for a PencilBlue database to reach 512MB, so you could probably go for a while on the sandbox database, if you needed to, although your performance wouldn't be optimal. Alternatively, the competing PaaS, mongolab, offers a similar free plan and 2GB of production storage for $15 per month, with each additional Gigabyte costing $5 extra.

As always, if you have any questions you can reach out to us on the contact page or on Twitter at @GetPencilBlue
© 2015 PencilBlue