Cloud Hosting: Heroku and Compose

Using Heroku and Compose to host your PencilBlue can be a quick and cost effective option. You can choose a developer sandbox setup for free or upgrade your setup to a faster, paid option.

Create a Heroku account and install the Heroku Toolbelt

Go to heroku.com 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.

Create a Compose account and free database

Go to Compose 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 you're database type (there's a free version) 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 Compose database and configure it for use.

From your database management screen, click on "connect directly to your database" and copy the Mongo URI code and paste it into a text editor. Remove ':@' from the URI, since PencilBlue will handle authentication directly and add a forward slash at the end. Your URI should look something like this: mongodb:/kahana.mongohq.com:10000/pbherokudemo/.

Naming your Heroku URL/Domain

At this point you should choose a unique name for your Heroku URL, even if you plan to use your own domain. Your application will be hosted at [app-name].herokuapp.com and any custom domains you may add. You should check your desired name in the browser to make sure it's not already taken by another Heroku app.

Install PencilBlue on your computer

Important: If you have not installed the pencilblue-cli to your system, follow the instructions for your operating system here.

Open a terminal, cd to the folder you want the PencilBlue folder to reside in, and run pencilblue install.

Enter the following when prompted (replace items in brackets with your own content):

site name: [your site's name]
site root: [your site's URL]
site IP: 0.0.0.0
site port: 8080
MongoDB URL: [your Mongo URI code]
database name: [your Compose database name]
Do you want to install Bower components: N

Prepare PencilBlue for Heroku

Once the installation is complete cd to the pencilblue directory and open config.js. Remove the line "sitePort": 8080, since Heroku will assign a port number and PencilBlue will automatically pick it up.

Add the following authentication element to the "db" section of config.js:

"authentication": {
    "un": "[your database username]",
    "pw": "[your database password]"
},

You're config.js file should now look something like this:

module.exports = {
    "siteName": "PencilBlue Heroku and MongoHQ Demo",
    "siteRoot": "http://pbherokudemo.herokuapp.com",
    "logging": {
      "level": "info"
    },
    "db": {
        "type": "mongo",
        "servers": [
            "mongodb://kahana.mongohq.com:10000/pbherokudemo/"
        ],
        "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
        }
    },
    "siteIP": "0.0.0.0"
}

We'll be using git to move the site up to Heroku, so remove the .gitignore file.

git rm .gitignore

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.

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].herokuapp.com 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 directly to the server. The Amazon S3 and Dropbox plugins will allow you to have full media capabilities in the admin section. If you choose to use one, add it to the plugins directory and repeat the Heroku push. If you want to keep things totally free, you can upload your photos to Imgur and link to them when creating media objects.

Troubleshooting

If navigating to your app in the browser throws an error, then the first thing you'll want to do is check the logs:

heroku logs

Walk through the steps of this quickstart guide and see if you missed one. If the logs show an authentication error with Compose, recheck the credentials you added. If that doesn't work, follow the steps in this troubleshooting doc from Compose.

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, that you used in config.js, to the list and save.

Change your domain's DNS settings to have a CNAME record pointing to [app name].herokuapp.com. Your website should be up and running on the new URL.