Public | Automated Build

Last pushed: a year ago
Short Description
This build creates image for the platform side of Just.
Full Description

Just Web Platform

Setup the development environment

Running Locally

This platform is built with Ruby on Rails 4.2.6, which requires Ruby version 2.2.2+. In addition to Ruby and Rails, install bundler for dependency management.

To run this platform locally, run bundle install to install dependencies.

Run rails server to start the web server listening at port 3000.

DB Setup

If using a local database run the following commands to run migrations:

bundle exec rake railties:install:migrations
bundle exec rake db:migrate

If you wish to seed your database with test data to use during development, run:

bundle exec rake db:reset
bundle exec rake seed:development_data

Using Docker

To run your development environment in a virtual Docker container you will need to install the Docker Toolbox, for docker commands see Understanding & Running the Dockerfiles

Payment Gateways

Follow the steps below or run rake payment_methods:stripe:setup to setup a working Stripe Payment Gateway.

  • Navigate to Configurations > Payment Methods in the Spree admin and click 'New Payment Method'
  • Select Spree::Gateway::StripeGateway in Provider
  • Set Display to Both
  • Set Auto Capture to true
  • Set Active to Yes
  • Fill in Name
  • Click Create
  • Once created, make sure that Test Mode is checked if using in test mode
  • Enter your keys in Secret Key and Publishable Key, making sure you're using test/live keys as applicable


To use the PayPal Payment gateway:

  • create an active Payment Method with provider: Spree::Gateway::PaypalApi in the admin (if starting from scratch you can also just run bin/rake seed:development_data, which will create it for you).
  • Set the env variables PAYPAL_CLIENT_ID, PAYPAL_SECRET, PAYPAL_EMAIL to the respective credentials. Also set JUST_HOST to whatever host you'll be using, like http://localhost:3000 (this is for the Paypal redirect urls).

Making a purchase

  • Add an item to your Cart and checkout as usual
  • At the Payment step, make a post request with the payment_method_id of the Custom PayPal API to the paypal endpoint.
  • This should return an approval_url. Visit it and fill in the required data. You can use a PayPal account or pay with debit/credit card. You can generate a fake credit card # here
  • Submit that form and you should be redirected to the return_url.
  • Once you hit the redirect page, submit the payment to the payment endpoint. In the PayPal params, the paymentId should be used as the payment_token and PayerID as payer_token.
  • You should receive the Order object back with state confirm. At this point you can post to the confirm endpoint which will complete and finalize the order.
  • The Order should appear as complete and paid in the Spree admin.
  • In the PayPal merchant account the payment status should be Complete (it may also be In Progress for a short time before being complete).


After you've made a valid purchase you can refund all or some of the total amount of the Order in the admin.

  • Navigate to the Order you created then Payments
  • Find the payment you'd like to refund and click on the minus sign.
  • This will take you to a page where you can set an amount and reason to refund.
  • After clicking 'Refund' you should be taken to the Payments page and the Refund should be visible.
  • This should also be reflected in the PayPal merchant account.


Voiding a transaction can only happen before an Order's payment is captured (once a payment is captured you'll need to issue a refund).

Because we are auto-capturing and skipping the Payment Review process in the sandbox there is currently no chance for us to test this (though it was tested thoroughly when we had auto-capture off). If you try to void a captured payment (clicking the X sign next to the payment) you will receive an error.

If necessary we can turn off auto-capturing to demonstrate.

Building Sample Orders For Testing

If you want to create an Order for testing purposes and don't feel like creating one manually in the console or via Postman, you can use the Order Builder rake task.

The rake task is run like:

bin/rake "order:build[address, 1 2 3 4, JUST10]"
  • address (required) is the Order state you'd like to achieve
  • 1 2 3 4 are the Variant id's you'd like to add as line items. If you don't specify any line items the task will choose a Variant for you.
  • JUST10 is a coupon code

The task launches a browser window which runs a javascript app that will create the Order via the api endpoints.

Since it's done in the browser the user will inherit the tokens (api_auth_token, just_api_csrf_token) required to perform subsequent api actions if necessary. e.g. if the default browser is Chrome then Postman will also have these tokens.

Using the rake task is not strictly necessary- you can also visit the endpoint at which the rake task is pointed, which looks like http://localhost:3000/order-builder/address?variant_ids=1,2,3,4&promo_code=JUST10.

####Order Builder Notes

  • Special characters in the promo_code param (like $) may cause issues when launching the browser from the rake task. If you need to use special characters it's easier to compose the order builder url and paste it into the browser to run the app.
  • Make sure you're not logged in as an admin when using the Order Builder
  • For the complete state, the payment gateway used is Stripe, since Paypal requires too many user interactions for automation
  • The Order Builder can only be run in the development environment for now


Tools and Practices

Spree Commerce

This project uses the open source Spree Commerce engine for core e-commerce functionality.

Active Admin

This project uses the open source Active Admin framework as a CMS foundation.

Folder Structure

├── app/
│   ├── admin/
│   ├── controllers/
│   ├── helpers/
│   ├── mailers/
│   ├── models/
│   ├── views/
├── config/
├── db/
├── docs/
└── test/
└── vendor/

app - Source of principal application code

app/admin - Folder that contains definitions of the CMS administrative interface

app/controllers - Controller classes

app/helpers - Utility classes

app/mailers - Email classes

app/models - Application models

app/views - View templates

config - Platform configuration files

db - Database scripts and Docker configuration

docs - API documentation generator code

test - Test code

vendor - Third party libraries (Spree & Active Admin)


We are using Swagger to generate versioned API documentation. This documentation will be hosted on the development and staging enviroments and regenerated on deployment as part of the CI build process.

To generate the API specification docs locally you must have Java and Node.
If these dependencies are met, you can install the Swagger Codegen tool. If you are on a Mac it is recommended to install using homebrew:

brew install swagger-codegen

Once you have the Swagger Codegen tool installed you are ready to render the docs and build a mock server, from the root of the project run:

cd docs/api/
swagger-codegen generate -i swagger.yaml -l nodejs-server -o tmp

This uses the API specification defined in docs/api/swagger.yaml to generate the frontend API documentation and a node server that returns mock data in the docs/api/tmp directory. To view the docs and the mock endpoints run:

cd tmp/
node .

The docs will now be available at http://localhost:8080/docs.

If you want to edit and validate the API specification, Swagger also provides a web-based editor that does live validation and updating and has some helpful sample specs.

Git Workflow


master - The branch holding the latest working copy of the project, the “head” of the trunk

feature branches - The branches containing granular work of all the developers aka the branch you will be working in. Naming convention should be JST-XXX where XXX is the trello card number. The Trello card numbers are in "Share and more" link at the bottom of the card's Actions list and in the URL.

Branch: JST-27

Commit Messages

Commit messages should be formatted like so:

JST-(Tello card number)- One sentence description of the work

Detailed commit description, if necessary.


At Work & Co we use a rebase workflow, which allows us to have a single-direction commit history. DO NOT MERGE. Merging can rewrite history and cause merge conflict disasters. To avoid spending too much time going through merge conflicts rebase daily. Here's a basic example of the workflow:

(JST-27) $ git checkout master
(master) $ git pull --rebase
(master) $ git checkout JST-27
(JST-27) $ git rebase master
  1. Make sure you rebase from master everyday. This will help you avoid having to work through a ton of merge conflicts.
  2. Commit to your feature branch granularly. Frequent small commits means if something terrible happens and your unstaged changes are removed, you won’t have much to lose. It also makes going back and cherry-picking is easy.
  3. Once your code is in tip-top shape and you're ready to submit a pull request, squash all of your commits. If you don't feel comfortable with interactive rebasing have a peer walk you through it until you're confident enough to do it on your own.
  4. Send your pull request. For this project, another developer has to approve your pull request before you can rebase it into the master branch.
  5. Make sure your local master branch is up-to-date and then rebase your feature branch with master to update the commit history.
  6. Rebase your feature branch into master.
  7. After the master branch is approved by QA and is ready to be promoted, the code gets tagged with a version name.

Example of a workflow:

Add click event
Fix padding
Add 1280 styles
Add 768 breakpoint styles
Start styling component


JST-27 - Adds styling and interaction for the dropdown used in registration forms.


Builds and Versioning

QA environment

Updates to QA environment must be executed manually, by pressing "build now" and specifying the dev build # on Work & Co's CI server.



Each sprint has a codename and can be found on semver.json. Every time the CI server (workci) kicks a build (when a push to master is made), it will increase the patch number of the version.

Completing a sprint

Upon sprint completion, one team member has to set the version to the sprint number. This is done by changing the version on package.json

** The plan is to keep version 0+ till beta, then move to 1+ for launch

Understanding & Running the Dockerfiles

There are two docker compose files in this repository. One will build the Swagger documentation and the other will bring up a development environment of the Just Platform.

Docker is run in a VM and thus that VM exposes an IP which you will find your containers running in. The easiest way to find the IP is to use Kitematic. However if you are running docker beta, you simply have to use 'localhost':

To Find The IP using Kitematic:

  • Click on the running container
  • Click on settings
  • Click on ports
  • The exposed port will be displayed

Find The IP By Command Line:

Open your terminal and type in the following command:

docker-machine ip

Building Swagger

Build the image:

docker-compose -f build

Run the image:

docker-compose -f up -d

To stop the image:

docker-compose -f stop

To remove stopped containers:

docker-compose -f rm -f

The documentation environments is exposed on port 4000. Simply navigate to <local-ip>:4000/docs

Using React in Active Admin

To use React components in development you'll want to start a local server which hosts the React assets. This allows for live code reloading, error notifications, etc. From the root directory:

npm install -g gulp
cd react
npm install

This will start the development server at http://localhost:8888.

Building The Development Environment

Build the image:

docker-compose -f ./docker/docker-compose.local.yml build

Run the Just Platform image:

docker-compose -f ./docker/docker-compose.local.yml up -d

Stop the running image:

docker-compose -f ./docker/docker-compose.local.yml stop

Remove stopped containers:

docker-compose -f ./docker/docker-compose.local.yml rm -f

Docker Pull Command
Source Repository