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 Mac for local development and testing.
  • Your team uses the standard tool chain of Docker for Mac and docker-sync for local development and testing.
  • You have the source(s) for the application(s) you're working with checked out locally on your Mac.
  • The application source(s) include the necessary Docker configuration files (generated by the workarea:docker generator, including the --sync option).
  • You have active credentials (username and password) to authenticate to the WebLinc gems server.

1. Install and Run Docker for Mac

If not already installed on your machine, follow the instructions from Docker to install and run Docker for Mac.

The process requires a Docker ID.

Docker provides Docker for Mac stable and edge channels. WebLinc recommends the stable channel, but the edge channel should also be compatible with the steps in this document.

2. Increase Resources Available to Docker

Within Docker for Mac, go to Preferences > Advanced and increase Memory to at least 4.0 GiB. Allocate more memory (e.g. 8.0 GiB) to improve performance, if you have the available resources.

3. Install Docker-sync

If not already installed on your machine, install docker-sync:

$ gem install docker-sync

4. Declare WebLinc Gems Server Credentials

In order for your local environment to authenticate to the WebLinc 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:

echo $BUNDLE_GEMS__WEBLINC__COM

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 within the default macOS terminal and 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:

BUNDLE_GEMS__WEBLINC__COM='fred:monkey123'

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

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

6. Start docker-sync

Start docker-sync:

$ docker-sync start

7. Start the Containers

Start the containers:

$ docker-compose up

You should eventually see the following text in the output, but it may take a while if this is the first time you are starting the containers for this application:

Puma starting in single mode...
Use Ctrl-C to stop

The containers are up and running. The docker-compose process will continue running (and logging) in the foreground of your shell session.

8. Open the Application in a Browser

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

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

Before seeding

9. Log In to a Shell within the Application Container

Get a new shell prompt using your method of choice (e.g. open a new terminal window or tab, or move the current job into the background), and run the following to start a shell session within the application container:

$ docker-compose exec web bash

The shell prompt has changed, indicating you are now logged in to the application container (your exact prompt will differ):

root@9713d0610f4c:/workarea#

10. Seed Development Data

At the new prompt, seed the application:

root@9713d0610f4c:/workarea# bin/rails db:seed

Reload the application in your browser to see the data:

Before seeding

Now you can develop.

11. Run Tests

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

root@9713d0610f4c:/workarea# 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:

root@9713d0610f4c:/workarea# bin/rails workarea:test

Now you can test.

12. Stop the Containers

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

To do so, return to your original shell session (e.g. change back to your original terminal tab/window, or bring the job back to foreground). Then press Ctrl + C, or otherwise send an interrupt signal (SIGINT) to the job/process.

docker-compose will try to gracefully stop the containers, producing output similar to the following:

Gracefully stopping... (press Ctrl+C again to force)
Stopping clothing-discounters_web_1           ... done
Stopping clothing-discounters_mongo_1         ... done
Stopping clothing-discounters_elasticsearch_1 ... done
Stopping clothing-discounters_redis_1         ... done

If you don't see this output, or if the process otherwise does not complete successfully, run the following to ensure the containers are stopped:

$ docker-compose stop

Repeating Steps

You're done!

However, you will need to repeat some or all of these steps under the following circumstances:

  • After checking out code changes (i.e. pulling your current branch to resume paused work, or checking out a new branch to begin new work), repeat steps 7-12.
  • To set up a new application (or set up the same application on a different machine), repeat steps 5-12.
  • To set up a new machine for development, repeat steps 1-12.

Multi Site Applications

If you are developing a multi site application (using the Workarea Multi Site plugin), you may find it inconvenient to restart the containers each time you want to change sites. You can use domain names to change sites more effeciently. See the Multi Site README for more details.