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:dockergenerator, including the
- You have active credentials (username and password) to authenticate to the WebLinc gems server.
1. 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:
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:
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>
$ cd $HOME/apps/clothing-discounters
6. 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
The application is running, but there is no data to work with:
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):
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:
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
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.