Create a New 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. These steps were written with the following assumptions:

For more details, see Prerequisites and Dependencies.

Create a New Rails Application

Follow the steps below to quickly set up a new Workarea application.

1. 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 \

2. Add Workarea gem

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

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

3. 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.

4. 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

5. 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:seeds

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

6. Start the Rails server

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

$ bin/rails server

7. Open the Application in a Browser

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


8. 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
rails workarea:test              # Run workarea tests (with decorators)
rails workarea:test:admin        # Run workarea admin tests (with decorators)
rails workarea:test:app          # Run all app specific tests
rails workarea:test:core         # Run workarea/core tests (with decorators)
rails workarea:test:decorated    # Run decorated tests
rails workarea:test:performance  # Run workarea performance tests (with decorators)
rails workarea:test:plugins      # Run all installed workarea plugin tests (with decorators)
rails workarea:test:storefront   # Run workarea storefront tests (with decorators)

This will run the Workarea test suite:

$ bin/rails workarea:test

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

9. 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.