Just Web Platform
Setup the development environment
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.
rails server to start the web server listening at port 3000.
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
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'
- Fill in
- Once created, make sure that
Test Modeis checked if using in test mode
- Enter your keys in
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::PaypalApiin 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_EMAILto the respective credentials. Also set
JUST_HOSTto 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
- Once you hit the redirect page, submit the payment to the payment endpoint. In the PayPal params, the
paymentIdshould be used as the
- 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
paidin the Spree admin.
- In the PayPal merchant account the payment status should be
Complete(it may also be
In Progressfor 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
- Find the payment you'd like to refund and click on the
- 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
Paymentspage 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 4are 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.
JUST10is a coupon code
Since it's done in the browser the user will inherit the tokens (
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
####Order Builder Notes
- Special characters in the
$) 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
completestate, the payment gateway used is Stripe, since Paypal requires too many user interactions for automation
- The Order Builder can only be run in the
developmentenvironment for now
Tools and Practices
This project uses the open source Spree Commerce engine for core e-commerce functionality.
This project uses the open source Active Admin framework as a CMS foundation.
/ ├── 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.
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.
Example: URL: XXXXX Branch: JST-27
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
- Make sure you rebase from master everyday. This will help you avoid having to work through a ton of merge conflicts.
- 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.
- 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.
- Send your pull request. For this project, another developer has to approve your pull request before you can rebase it into the
- Make sure your local
masterbranch is up-to-date and then rebase your feature branch with
masterto update the commit history.
- Rebase your feature branch into
- After the
masterbranch is approved by QA and is ready to be promoted, the code gets tagged with a version name.
Example of a workflow:
[JST-27 BRANCH] Add click event Fix padding Add 1280 styles Add 768 breakpoint styles Start styling component [SEND PULL REQUEST] [PULL REQUEST APPROVED] [SQUASH ALL GRANULAR FEATURE COMMITS AND FORMAT] JST-27 - Adds styling and interaction for the dropdown used in registration forms. [REBASE INTO DEV] [DELETE BRANCH]
Builds and Versioning
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
** 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:
Build the image:
docker-compose -f docker-compose.docs.yml build
Run the image:
docker-compose -f docker-compose.docs.yml up -d
To stop the image:
docker-compose -f docker-compose.docs.yml stop
To remove stopped containers:
docker-compose -f docker-compose.docs.yml rm -f
The documentation environments is exposed on port
4000. Simply navigate to
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 gulp
This will start the development server at
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