Code Climate Build Status Dependency Status Coverage Status Inline docs Gitter chat Stories in Ready

Supermarket is Chef's new community project with the goals of being the community repository for cookbooks, an easy to contribute to project, and the behind-the-firewall solution to serving cookbooks.

The goal of this README is to introduce you to the project and get you up and running. More information about Supermarket can be found in the wiki. Supermarket is currently pre-release and under active development. View the roadmap, and follow along with the project development in Supermarket has an open project chat on Gitter and a mailing list.

If you want to contribute to Supermarket, read the contributor's workflow for license information and helpful tips to get you started. There are project artifacts such as planning docs, wireframes, recorded demos, and team retrospectives in a public Google Drive folder and on InVision.

If you have questions, feature ideas, or other suggestions, please open a GitHub Issue.

This repository has the code for the Supermarket application, related repositories are:


  • Ruby 2.1.3
  • PostgreSQL 9.3+
  • Redis 2.4+



Configure the dotenv keys and secrets to . See .env.example for required keys and secrets to get up and running. docs/ goes into detail about the not so straight forward configuration that needs to happen to get Supermarket working locally.

Using Vagrant (Beginner)

Supermarket includes a collection of Chef cookbooks and a preconfigured Vagrantfile to make it easy to get up an running without modifying your local system.

  1. Install VirtualBox and Vagrant

  2. Install the vagrant-omnibus plugin:

  1. Install the vagrant-berkshelf plugin:
  1. Run the server:

The next time you want to start the application, you only need to run:

$ ./bin/supermarket server

About Vagrant

Vagrant uses VirtualBox to run a VM that has access to the application project files. It syncs your local project files with the VM. Running the ./bin/supermarket server command spins up a VM. When you are done running the application, do not forget to run vagrant suspend or vagrant halt to give the VM a break.

You can read more about Vagrant teardown in the Vagrant docs.

Read more about changing the Vagrant VM defaults in the wiki.

Guest Additions

If you get an error about Guest Additions, install the vagrant-vbguest vagrant plugin:

$ vagrant plugin install vagrant-vbguest

Switching from Vagrant to Local Environment Development

If you want to switch from Vagrant to your developing locally, you have two options:

When Vagrant runs bundle install it installs the gems into vendor/ruby/gems. This is because of the Bundler config in .bundle/config.

  1. If you want to continue to install gems in vendor/ruby/gems, delete that directory and run bundle install. This will rebuild the gems with native dependencies on your local machine instead of the Vagrant VM.
  2. If you want to install your gems system wide, delete the .bundle directory.

Local Environment (Advanced)

  1. Install Ruby 2.0 (latest patch) using your favorite Ruby manager
  2. Install Postgres (from homebrew or the app) NOTE: This application requires Postgresql version 9.2. Homebrew will install a later version by default. To install the earlier version using homebrew see this stack overflow
  3. Install Redis (required to run background jobs)
  4. Make sure both Postgres and the Redis server are running
  5. Install bundler
  1. Install required gems:
  1. Create the database, migrate the database and seed the database:
  1. Add required Postgres extensions.
  1. Start the server:


Run the entire test suite (rspec, rubocop and mocha) with:

$ bundle exec rake spec:all

Acceptance Tests

Acceptance tests are run with Capybara. Run rake spec:features to run the specs in spec/features. The default rake spec also runs these.

When writing a feature, use require 'spec_feature_helper' instead of spec_helper to require the extra configuration and libraries needed to run the feature specs.

When writing feature specs, the Rack::Test driver is used by default. If the Poltergeist driver is required to be used (for example, an acceptance test that uses AJAX), add the use_poltergeist: true metadata to the spec. See the remove_members_from_ccla_spec.rb spec for an example.

Some specs run using PhantomJS, which must be installed for the test suite to pass.

JavaScript Tests

The JavaScript specs are run with Karma and use the Mocha test framework and the Chai Assertion Library

The specs live in spec/javascripts. Run rake spec:javascripts to run the specs, and rake spec:javascripts:watch to run them continuously and watch for changes.

Node.js is required to run the JavaScript tests.

Background Jobs

Read about Supermarket's background jobs in the wiki.


Read about Deployment instructions in the wiki.

Feature Flags

Supermarket uses a .env file to configure itself. Inside this file are key/value pairs. These key/value pairs will be exported as environment variables when the app runs, and Supermarket will look for these keys as environment variables when it needs to read a value that's configurable.

One of these keys is called FEATURES and it controls a number of features that can be turned on and off. Here are the available features that can be toggled:

  • cla
  • join_ccla
  • tools
  • fieri
  • announcement
  • github
  • no_crawl