Quick Start

Follow the steps below to quickly set up your computer and Workarea applications for local development and testing.

These steps were written with the following assumptions:

  • You use a Unix-like operating system (OS X or Linux) for local development and testing.
  • You have Docker Desktop and Docker Compose installed. For download instructions see
    • https://www.docker.com/products/docker-desktop and
    • https://docs.docker.com/compose/install/
  • You have Ruby installed. For instructions see:
    • https://github.com/rbenv/rbenv#homebrew-on-macos for OS X via Homebrew, or
    • https://github.com/rbenv/rbenv#basic-github-checkout for Linux
  • You have active credentials (username and password) to authenticate to the Workarea gems server.
  • You have the source(s) for the application(s) you're working with checked out locally on your machine
  • You are not already running Redis, MongoDB or Elasticsearch on your machine

1. Declare Workarea Gems Server Credentials

In order for your local environment to authenticate to the Workarea gems server, the environment variable BUNDLE_GEMS__WEBLINC__COM (notice the double underscores) must be set.

Run the following to see if this variable is already set within your environment:


If blank, set the variable to a string in the format <user>:<password>. The process to do this varies by shell and personal preference. The following template works for machines running bash shell:

echo 'export BUNDLE_GEMS__WEBLINC__COM='\''<user>':'<password>'\' >> $HOME/.profile

Here's a concrete example:

echo 'export BUNDLE_GEMS__WEBLINC__COM='\''fred':'monkey123'\' >> $HOME/.profile

The preceding example appends a line to the .profile configuration file in your home directory. The new line looks like this:


Be cautious of shell special characters. For example, if your password contains a single quote, the quoting in the examples above will not work.

2. Change to the Application Directory

The remaining steps are specific to an application, so change to the application's directory within your shell:

$ cd <your-application-directory>

For example:

$ cd $HOME/apps/clothing-discounters

2. Install the Application's gems

Gems are Ruby's package management system. Bundler is the tool for managing gem versions and dependencies.

Install bundler:

$ gem install bundler

And then install the "bundle" of gems for this application:

$ bundle install

2. Start Workarea services

Start the services Workarea depends on. This includes MongoDB, Redis, and Elasticsearch:

$ bin/rails workarea:services:up

There are now containers for services running specifically for this application. You can see them by running docker ps.

3. Start the Rails server

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

$ bin/rails server

If you are developing a multi site application (using the Workarea Multi Site plugin), you can specify the site in an environment variable when starting the Rails server, e.g. SITE_ID=chocolate bin/rails server. See the Multi Site README for more details.

4. Open the Application in a Browser

Open a web browser, and browse to http://localhost:3000.

The application is running, but there is no data to work with:

Before seeding

5. Seed Development Data

At the new prompt, seed the application:

$ bin/rails db:seed

Reload the application in your browser to see the data:

Before seeding

Now you can develop.

4. Run Tests

At the same prompt, run bin/rails -T test, for example:

$ bin/rails -T test
rails test                       # Runs all tests in test folder except system ones
rails test:db                    # Run tests quickly, but also reset db
rails test:system                # Run system tests only
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)

The output explains how to run tests. For more details, see Running Tests.

The following example runs the platform test suite, including the extensions (decorators) to those tests within your application:

$ bin/rails workarea:test

Now you can test.

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