Logistics Wizard / Architecture / logistics-wizard-controller

Logistics Wizard Controller

This service orchestrates interaction between Logistics Wizard's services.

Run the app on IBM Cloud

1. If you do not already have an IBM Cloud account, sign up here.

2. Download and install the IBM Cloud CLI.

3. The Controller depends on the ERP and Recommendation microservices. Deploy them first.

4. Clone the Controller to your local environment from your terminal using the following command.

git clone https://github.com/IBM-Cloud/logistics-wizard-controller.git

5. Change directory using cd logistics-wizard-controller.

6. Open the manifest.yml file and change the host value to something unique. The host you provide will determine the subdomain of the Controller's URL: <host>.mybluemix.net.

7. From the command line, connect to IBM Cloud and follow the prompts to log in.

ibmcloud api https://api.ng.bluemix.net
ibmcloud login

8. Push the controller to IBM Cloud.

ibmcloud app push --no-start

9. Define the environment variable pointing to the ERP service.

ibmcloud app set-env logistics-wizard-controller ERP_SERVICE <url-to-erp-service-here>

10. Set the URL used to call the actions of the Recommendation service, eg https://us-south.functions.cloud.ibm.com/api/v1/web/<namespace-id>/<package-name>:

ibmcloud app set-env logistics-wizard-controller FUNCTIONS_NAMESPACE_URL "url-to-the-namespace-web-actions"

11. Start the Controller.

ibmcloud app start logistics-wizard-controller

And voila! You now have your very own instance of the Logistics Wizard's Controller running on IBM Cloud.

Run the app locally

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

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

git clone https://github.com/IBM-Cloud/logistics-wizard-controller.git

3. Change directory using cd logistics-wizard-controller.

4. In order to create an isolated development environment, you 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. Start the app

python bin/start_web.py

To override values for your local environment variables create a file named .env.local from the template below and edit the file to match your environment.

cp template-env.local .env.local

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_unit_tests.py

Integration Tests

Similar to the unit tests, integration tests validate the communication between the controller and other services such as the ERP service. These tests require the ERP service to be running.

To run the tests, execute the following command:

python server/tests/run_integration_tests.py

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

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_unit_tests.py
$ coverage --append run server/tests/run_integration_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: To pass, the integration tests require an ERP service to be running.

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:

Troubleshooting

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

$ ibmcloud app logs logistics-wizard-controller --recent

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

License

See License.txt for license information.

Status

master
dev