Deploying to Heroku

peakpg edited this page Jun 5, 2013 · 14 revisions

In BrowserCMS 3.5.0, we are improving the support for deploying CMS sites to Heroku. This page covers how to set up and deploy a BrowserCMS site on Heroku. In general, using Heroku should work reasonable well, though there are some constraints to consider (see 'Overview' below).

If you have issues, feedback or questions setting up on Heroku, please post them to the mailing list.


Deploying to Heroku is slightly different then other servers due to the constraints of the platform. In particular:

  1. No Page Caching: The CMS typically relies on Rails page caching working in conjunction with the web server for performance. Page caching isn't available on Heroku, so for the time being, caching is not used. We are aiming to make caching more configurable in upcoming versions.
  2. Subdomains: The typical configuration of a site will have multiple subdomains (one for the 'public' site, and another for the 'admin' site.). Heroku now supports wildcard domains for free (on Cedar), so BrowserCMS can use the typical subdomain setup.
  3. No file storage: Uploaded files cannot be stored on heroku so you must use an external host, such as AWS S3. There is module bcms_aws_s3 which can be used to store files. The module seemlessly handles sending and storing files on S3. See the installation instructions for that module for more details.
  4. Postgresql - BrowserCMS is most well tested with MySQL and/or Sqlite. Heroku uses Postgresql as its default database. At this time, it appears as though BrowserCMS works just fine with Postgresql in production. However, you may want to generate a new browsercms project locally using sqlite3 locally for testing, then switch the database to postgresql after.

Before starting this, review the Rails 3 Heroku guide found here.

1. Instructions

1a. Generate the project

We create the project (using sqlite)

$ bcms new my_heroku_site

This may also work (depending on your local machine setup)

$ bcms new my_heroku_site -d postgresql

1b. Configure Postgresql in production

Ensure your project is configured to use postgresql in production (at least).

# Gemfile
gem 'sqlite3', :group=>:development
gem 'pg', :group=>:production
# config/database.yml
  adapter: postgresql
  encoding: unicode
  database: heroku_app_production
  pool: 5
  username: heroku_app_user
  password: heroku_app_pw

1c. Set up the S3 module

Follow the installation instructions for the bcms_aws_s3 module.

1d. Setup Heroku project

First setup a git project.

$ git init
$ git add .
$ git commit -m "Initial setup"

Install Heroku and configure the project to deploy to it. See the Rails 3 Heroku guide for more info.

$ gem install heroku
$ heroku create
$ git push heroku master
$ heroku run rake db:install

Modify the Gemfile to match the heroku deployment environment. This sample Gemfile is a reasonable start. Then check in your changes and deploy the site.

Take note of the domain name that was generated when heroku create was run above (something like:, as well as the cmsadmin password generated when running rake db:install

1e. Enable wildcard subdomains

Run the following, substituting your generated domain name above.

$ heroku domains:add *

You can now access the site at and the admin site at You may want to set up a redirect from to for consistency.

2. Configuration Options:

Single Domain mode

If you don't want to bother with subdomains, you can disable them. This will allow BrowserCMS to run on a single domain (no redirects), but will turn off page caching completely.

# config/environments/production.rb
config.cms.use_single_domain = true

3. Asset Precompiling

If you are having issues with compiling assets, you can also try adding the following to your production.rb, which will avoid initializing the environment during precompiling.

config.assets.initialize_on_precompile = false


Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.