Logistics Wizard Overview

WORK IN PROGRESS

This repository serves as the central server application for the Logistics Wizard application and acts as the main controller for interaction between the system's services.

Logistics Wizard is a reimagined supply chain optimization system for the 21st century. It is comprised of a set of loosely-coupled, distributed services that take an existing ERP system and extend its functionality by leveraging various cloud services. The goal of this system is to showcase several common SaaS implementation patterns and provide them to our developer community. This demo exhibits hybrid cloud, microservices, and big data anlytics concepts that can be reused when building enterprise-level applications on Bluemix.

The following services are leveraged in the overall Logistics Wizard solution, yet are built to be extensible for other purposes:

• logistics-wizard-erp
• logistics-wizard-recommendation

To deploy the full system all at once, check out the Logistics Wizard Toolchain

![Architecture](http://g.gravizo.com/g? digraph G { node [fontname = "helvetica"] rankdir=RL user -> controller [label="1 - Makes a request"] recommendations -> discovery [headlabel="2 - Registers and sends heartbeat" labeldistance=12 labelangle=-16] erp -> discovery [label="3 - Registers and sends heartbeat"] controller -> discovery [taillabel="4 - Query for services" labeldistance=8 labelangle=-7] controller -> erp [label="5 - CRUD SCM data"] controller -> recommendations [label="6 - Retrieve/update recommendations" dir="back"] {rank=max; user} {rank=same; erp -> controller [style=invis]} {rank=same; controller -> recommendations [style=invis]} {rank=min; discovery} /* styling */ user [shape=diamond width=1 height=1 fixedsize=true style=filled color="black" fontcolor=white label="User"] erp [shape=rect style=filled color="%2324B643" fontcolor=white label="ERP"] controller [shape=rect label="Controller API"] recommendations [shape=rect style=filled color="%2324B643" fontcolor=white label="Recommendations"] discovery [shape=circle width=1 fixedsize=true style=filled color="%234E96DB" fontcolor=white label="Service\nRegistry"] } )

Running the app on Bluemix

1. If you do not already have a Bluemix account, sign up here

2. Download and install the Cloud Foundry CLI tool

3. Clone the app and its submodules to your local environment from your terminal using the following command:

   $ git clone --recursive https://github.com/IBM-Bluemix/logistics-wizard.git

4. cd into this newly created directory

5. Open the manifest.yml file and change the host value to something unique.

The host you choose will determinate the subdomain of your application's URL: <host>.mybluemix.net

6. Connect to Bluemix in the command line tool and follow the prompts to log in.

   $ cf api https://api.ng.bluemix.net
   $ cf login

7. Push the app to Bluemix.

   $ cf push

And voila! You now have your very own instance of Logistics Wizard running on Bluemix.

Run the app locally

1. If you have not already, download Python 2.7 and install it on your local machine.

2. Clone the app to your local environment from your terminal using the following command:

$ git clone --recursive https://github.com/IBM-Bluemix/logistics-wizard.git

3. cd into this newly created directory

4. In order to create an isolated development environment, we will be using Python's virtualenv tool. If you do not have it installed already, run

$ pip install virtualenv

Then create a virtual environment called venv by running

$ virtualenv venv

5. Activate this new environment with

$ source .env

6. Install module requirements

$ pip install -r requirements.dev.txt

7. Finally, start the app

$ python bin/start_web.py

To get values for your local environment variables in .env.local, check out the Setting up email section.

Testing

Unit Tests

There are series of unit tests located in the server/tests folder. The test suites are composed using the Python unittest framework. To run the tests, execute the following command:

$ python server/tests/run_tests.py

The tests will print a dot for each successfully completed unit test. If a test fails for any reason, it will mark that test with either an F or E and print the reason for any failed tests after the test suites are all completed. For example, here is the output of a successfully complete test_demos_service.py test:

(venv) MyMac:logistics-wizard User$ python server/tests/test_demos_service.py 
.......
----------------------------------------------------------------------
Ran 7 tests in 30.597s

OK

Travis CI

One popular option for continuous integration is Travis CI. We have provided a .travis.yml file in this repository for convenience. In order to set it up for your repository, take the following actions:

1. Go to your Travis CI Profile

2. Check the box next to your logistics-wizard GitHub repository and then click the settings cog

3. Create the following environment variables

   • LOGISTICS_WIZARD_ENV - TEST
   • SMTP_SERVER - smpt.gmail.com
   • SMTP_SERVER_PORT - 587
   • SMTP_USER_NAME
   • SMTP_PASSWORD

   To get values for the SMTP_USER_NAME and SMTP_PASSWORD variables, check out the Setting up email section.

Thats it! Now your future pushes to GitHub will be built and tested by Travis CI.

Code Coverage Tests

If you would like to perform code coverage tests as well, you can use coveralls to perform this task. If you are using Travis CI as your CI tool, simply replace python in your test commands with coverage run and then run coveralls as follows:

$ coverage run server/tests/run_tests.py
$ coveralls

To determine how to run coveralls using another CI tool or for more in-depth instructions, check out the coveralls usage documentation.

Note: The unit tests are currently hitting the production version of the logistics-wizard-erp application. In the future these tests will be able to be run in isolation.

Setting up email

In order to send welcome emails, we need to configure the app to use an SMTP server. For simplicity's sake, we will use the free SMTP server that Gmail provides. This section will walk you through how to do this:

1. Create a new Gmail account to serve as the FROM address for your application's emails

2. Turn on Gmail access for less secure apps so that your app will be able to send emails on your behalf

3. Go to the Forwarding/IMAP tab in your Gmail settings and make sure IMAP is enabled. This ensures emails are properly copied into your sent folder.

4. Lastly, your Gmail username and password must be copied to the service you are using for deployment. Here are some common options:

   • CF CLI: Update the environment variables in your manifest.yml file or in your app dashboard's Runtime --> Environment Variables section after deployment.
   • DevOps Services Toolchain: When configuring your toolchain, set the email parameters in the Delivery Pipleine section.
   • Travis CI: Go to the Settings tab for your repo and update the environment variables there.
   • .env.local: If you would like to test this functionality while developing locally, copy the values into this file.

Your app should now be capable of sending welcome emails to any end users that include their email address during signup.

Note: Be aware that Google restricts the number of messages sent per day to 99 emails. The restriction is automatically removed within 24 hours after the limit was reached.

API documentation

The API methods that this component exposes requires the discovery of dependent services, however, the API will gracefully fail when they are not available.

The API and data models are defined in this Swagger 2.0 file. You can view this file in the Swagger Editor.

Use the Postman collection to help you get started with the controller API:

Contribute

Please check out our Contributing Guidelines for detailed information on how you can lend a hand to the Logistics Wizard demo implementation effort.

Troubleshooting

The primary source of debugging information for your Bluemix app is the logs. To see them, run the following command using the Cloud Foundry CLI:

$ cf logs logistics-wizard --recent

For more detailed information on troubleshooting your application, see the Troubleshooting section in the Bluemix documentation.

Privacy Notice

The logistics-wizard sample web application includes code to track deployments to Bluemix and other Cloud Foundry platforms. The following information is sent to a Deployment Tracker service on each deployment:

• Python package version
• Python repository URL
• Application Name (application_name)
• Space ID (space_id)
• Application Version (application_version)
• Application URIs (application_uris)
• Labels of bound services
• Number of instances for each bound service and associated plan information

This data is collected from the setup.py file in the sample application and the VCAP_APPLICATION and VCAP_SERVICES environment variables in IBM Bluemix and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Bluemix to measure the usefulness of our examples, so that we can continuously improve the content we offer to you. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.

Disabling Deployment Tracking

Deployment tracking can be disabled by removing cf_deployment_tracker.track() from the server/web/__init__.py file.

License

See License.txt for license information.