Build your Ruby web application with Habitat

This guide shows how to use the Ruby scaffolding to build and run your Ruby web application with Habitat. It explores how to extend and customize your Habitat package based on common overrides to the default scaffolding behavior. For the complete reference on how to use the Ruby scaffolding, see the reference topic that accomplanies the scaffolding source code.

In this guide

The following steps provide a framework for how to use the Ruby scaffolding; however, you are not required to read them in order. Feel free to move back and forth between topics as you create the plan for your web application.

  • Create Your Plan: Learn how to use the scaffolding to create a basic structure for your plan.
  • Define Dependencies and Callbacks: Understand how to add runtime dependencies for your web application.
  • Define Build Logic For Your App: Define how source code for your web application is built and installed as part of the package creation process.
  • Define Hooks: Define runtime behavior for your application.
  • Define Environment Variables: Set and configure environment variables that can be used at runtime.
  • Define Processes: Define tasks for binaries included in your web application.
  • Add Configuration: Specify which settings on your web application can be configured at runtime.
  • Build and Test: Learn how to build, test, and run your web application package.
  • Connect to a Database: Describes how to connect your web application to a PostgreSQL database through a container, in the cloud, or in a lcoal cluster.
  • Connect to Nginx: Explains how you can use the popular web server Nginx as a reverse proxy for your web application.
  • Next Steps: Provides suggested topics for further reading within the reference documentation and blog posts.


Download and install the Habitat CLI (command-line interface) on your workstation. You should complete all steps before doing any local development work with the CLI.

Also, this guide assumes that you have a Ruby web application already created with a Gemfile in your project directory.

Important If you have the gem tzinfo-data referenced in your Gemfile, it is important that you remove any platform-specific attributes from the gem declaration. Your reference should simply look like the following:

gem 'tzinfo-data'
Next: Create Your Plan