Create a New Workarea App

This is a quick start guide for getting started on a brand new Workarea application. If you're new to developing on Workarea this is a great place to start.

If you experience a problem while following these instructions, get help on the Workarea Community Slack or open an issue on GitHub.

After reviewing the assumptions, complete the following steps to create a new Workarea application and open it in your browser:

  1. Create a Rails 5.2 application
  2. Add the Workarea gem
  3. Install Workarea into the Rails application
  4. Start Workarea service dependencies
  5. Seed the database
  6. Start the Rails server
  7. Open the application in a browser

Then, you may want to run tests and stop the services.


The steps that follow assume the following:

For more details, see Prerequisites and Dependencies.

TL;DR Video Walkthrough

Workarea Dev Quickstart from Workarea Commerce Platform on Vimeo.

Create a Rails 5.2 application

This creates a barebones Rails app for Workarea to install into:

mkdir my-store && cd my-store
echo "source ''" > Gemfile
echo "gem 'rails', '~> 5.2'" >> Gemfile
bundle install
bundle exec rails new ./ --force \
--skip-spring \
--skip-active-record \
--skip-action-cable \
--skip-puma \
--skip-coffee \
--skip-turbolinks \
--skip-bootsnap \
--skip-yarn \

Add the Workarea gem

This adds the Workarea base gem to the project and updates dependencies:

echo "gem 'workarea'" >> Gemfile
bundle update

Install Workarea into the Rails application

Workarea ships with an installer generator that will configure the application:

bin/rails generate workarea:install

For more details on what this generator does, see Installing Workarea.

Start Workarea service dependencies

Workarea relies on a few databases, so there's a task that will start them in Docker containers. Start Workarea dependencies:

bin/rails workarea:services:up

Seed the database

To do anything useful with Workarea, you'll want some sample data in your database. The install generator run in step 3 will add Workarea seeds to your db/seeds.rb file, so running Rails seeds will add sample Workarea data.

bin/rails db:seed

For more details on working with seed data, see Seeds.

Start the Rails server

Use the conventional Rails command for starting up the Puma server:

bin/rails server

Open the application in a browser

Your Workarea application is ready! Open a browser, and check out http://localhost:3000.

Run tests

Running tests is a regular part of developing on Workarea. Check out the list of Rails tasks Workarea provides for testing Workarea:

bin/rails -T workarea:test

Try one of the test runners listed in that output. For example, this will run the Workarea test suite:

bin/rails workarea:test

For more details on Workarea's testing functionality, see Testing.

Stop the services

After developing and testing, you may want to stop the services to conserve resources on your machine.

Run the command to stop the services Workarea has started for you:

bin/rails workarea:services:down

Note that the volumes these containers used will still be available, and you won't have to seed again the next time you start them.

Now on GitHub