master
dev

Acme Freight Controller

This service is part of the larger Acme Freight project.

Overview

This service acts as the main controller for interaction between the system's services.

To automatically deploy this application to Bluemix as part of the larger Acme Freight application, refer to the Bluemix DevOps toolchain on the parent repository.

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. The app depends on the ERP and Recommendation microservices. These applications are deployed automatically as part of the toolchain on the parent acme-freight repository.

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

   git clone https://github.com/ibm/acme-freight-controller.git

5. cd into this newly created directory

6. 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

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

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

2. Push the app to Bluemix.

   cf push --no-start

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

cf set-env acme-freight-controller ERP_SERVICE <url-to-erp-service-here>

1. Define the OpenWhisk auth key and the package where the actions of the Recommendation service have been deployed

cf set-env acme-freight-controller OPENWHISK_AUTH "your-auth-key"
cf set-env acme-freight-controller OPENWHISK_PACKAGE lwr

1. Start the app.

cf start acme-freight-controller

And voila! You now have your very own instance of the Acme Freight controller 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 https://github.com/ibm/acme-freight-controller.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 override values for your local environment variables create a file named .env.local from the template:

cp template-env.local .env.local

and edit the file to match your environment.

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 as the unit tests but they validate the communication between the controller and the other services, like the ERP service. These tests require a 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 acme-freight GitHub repository and then click the settings cog

3. Create the following environment variables

   • ACME_FREIGHT_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 Bluemix app is the logs. To see them, run the following command using the Cloud Foundry CLI:

$ cf logs acme-freight-controller --recent

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

Privacy Notice

The acme-freight 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 for license information.