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
- 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>
$ 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.
$ 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
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
The application is running, but there is no data to work with:
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:
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
How'd We Do?
Was this article missing something?
Was it not quite what you were looking for?
Do you have suggestions on how we could improve this article or your experience in general?
If so, please take a moment to let us know!
Your invaluable feedback will help everyone better understand the platform!