Deploying to Heroku

The goal of this page is to explain the changes you may need to make in order to deploy your Aqua app to Heroku.

Procfile

Heroku uses a special file named /Procfile (no extension), that resides in the root of your project. For the live demo our /Procfile simply contains:

web: node server.js

You can read more about these here: https://devcenter.heroku.com/articles/procfile

Dependencies and build files

By default when you deploy to Heroku, it doesn't install devDependencies. But our client-side assets need to be compiled. And the compiling is done using some tools we keep in devDependencies. There are a few different approaches to get this working:

• Move all the necessary dependencies from devDependencies into dependencies.
  • Not great when you like to have a distinct separation between what things are required to run the app vs what things are required during development and to compile the assets.
• Stop .gitignoreing your /node_modules and /public directories and commit everything to your repo.
  • This is a common practice and can help make your app more resilient to changes in modules you didn't expect or that introduce breaking changes without following semver conventions.
• Add a Heroku config variable NPM_CONFIG_PRODUCTION=false which will signal npm to install all dependencies, not just production dependencies.
  • This is kind of a lazy solution that allows us to keep our devDependencies separated but does leave us open to changes in other modules. Because Aqua is a boilerplate we chose not to commit dependencies to our repo and leave that decision up to you.

For the live demo of Aqua we chose to go with that latter option. By following these these instructions, we added a config var NPM_CONFIG_PRODUCTION=false. You can do this via the heroku command line client or via the web interface.

Then we added a postinstall script to our package.json to run $ gulp build after all dependencies have been installed.

{
  "name": "Aqua",
  "scripts": {
    // ...
    "postinstall": "gulp build"
  }
  // ...
}

If you're committing your compiled assets to your repo, you may not need a postinstall script.

MongoDB instance

For the live demo we used the mLab add-on.

$ heroku addons:create mongolab:sandbox

If you choose a different database provider, just be sure to set the MONGODB_URI environment variable.

Seeding your database

The first time you deploy to Heroku you'll need to seed the database. You generally have two options here:

1. Import the data. See your database provider for details on how.
2. Run the setup script on your Heroku instance.

Running setup on Heroku

From within your project's root folder run this command in your terminal:

$ heroku run npm run first-time-setup --app getframe
# Running npm run first-time-setup on ⬢ getframe... up, run.9873

Which is just like when you do it locally when setting up Aqua for the first time, just remotely on your Heroku instance.

That's it

We hope this was helpful. If you have questions or think this page should be expanded please contribute by opening an issue or updating this page.