Quickstart Tutorial
In this tutorial, you will:
- Deploy the reference implementation to a standalone OpenShift cluster.
- Create an order via the UI.
- Check on existing orders.
- View information about the Fleet.
Each of these business processes will be executed step-by-step using the demonstration APIs and some scripts.
Pre-requisites
- Red Hat OpenShift Container Platform - this quickstart utilizes learn.openshift.com Playgrounds.
- … and that’s it!!! Everything else is provided for you via OpenShift Operators or through existing GitHub repositories.
- Additional self-paced learning can be done to integrate the deployed reference implementation with additional Kafka offerings, such as IBM Event Streams, Red Hat AMQ Streams, or Confluent Platform.
Step 1: Deploy the reference implementation
Go to
https://learn.openshift.com/playgrounds/openshift45/in a browser and click Start Scenario.From a terminal that has access to your OpenShift cluster, download the kcontainer-quickstart-ocp.sh file:
curl -o kcontainer-quickstart-ocp.sh https://raw.githubusercontent.com/ibm-cloud-architecture/refarch-kc/master/scripts/kcontainer-quickstart-ocp.shchmod +x kcontainer-quickstart-ocp.sh- The quickstart script is written for the most basic of OpenShift environments provided via learn.openshift.com.
- To override the default username and password used in the quickstart script for use in a different OpenShift environment, set environment variables with names of
OCP_ADMIN_USERandOCP_ADMIN_PASSWORDto the appropriate values before executing the script.
Execute the quickstart deployment script with the following command:
./kcontainer-quickstart-ocp.shWait for the deployment to be active and ready when you are prompted with
Press any key to continue once an order has been submitted....When accessing the user interface in the following steps, you should use the Route that exposes
kc-uimicroservice, which should be output in the terminal directly above the prompt.- This will be referred to as
kc-ui-shipping.cluster.localin the steps below.
- This will be referred to as
Step 2: KContainer Manufacturer creating an order
Orders are created via the manufacturer. For a reminder of the different personas, view the Scenario Overview.
- Navigate to
http://kc-ui-shipping.cluster.local(replacing the actual URL of thekc-uimicroservice with the value output while running the quickstart script or available viaoc get route kc-ui) to access the UI home page:
To log in to the home page, you will need the following user email and password:
- Email: eddie@email.com
- Password: Eddie
The initial UI homepage shows an illustrated version of the business process. There are four tiles that can be used to simulate different parts of the outlined business process.
- From the
Initiate Orders - Manufacturercreate a new ‘fresh product’ order to ship overseas. This simulates the activity that would usually be carried out by the manufacturer in our scenario.
To represent different manufacturers, the first select box has been designed to support multiple scenarios in the future. For the purposes of this quickstart tutorial, select ‘GoodManuf’.
Once the manufacturer is selected, a list of existing orders will be displayed.
- Select one order using the
Arrowicon. This will allow you to view the order details:
As illustrated in the CQRS diagram:
The creation of the order goes to the Order Command microservice which publishes an OrderCreated event to the orders topic and then consumes it to persist the data to its database. See the source code here.
- We can create a consumer to take messages from the
orderstopic by running the following command from the same terminal the quickstart deployment script was run from:
oc rsh my-cluster-kafka-0 bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --from-beginning --timeout-ms 10000 --topic orders
After running this, you should be able to see the following order with the status of pending and the type of event being OrderCreated.
{"payload":{"orderID":"1fcccdf2-e29d-4b30-8e52-8116dc2a01ff","productID":"Carrot","customerID":"GoodManuf","quantity":10000,"pickupAddress": "...","expectedDeliveryDate":"2019-03-31T13:30Z","status":"pending"},"type":"OrderCreated",
Step 2: K Container Shipment Manager looking at Orders
- From the home page, click on the Shipment Manager - Shipping Inc tile:
The home page lists the order that the shipment company received in the previous step.
The status of events will be modified over time while the order is processed down stream by the voyage and container services. The following sequence diagram illustrates the flow:
Looking at the events in the voyage service
voyages_1 | emitting {"timestamp":1548788544290,"type":"OrderAssigned","version":"1","payload":{"voyageID":100,"orderID":"1fcccdf2-e29d-4b30-8e52-8116dc2a01ff"}}
or on the orders topic:
{"timestamp":1548792921679,"type":"OrderAssigned","version":"1","payload":{"voyageID":100,"orderID":"1fcccdf2-e29d-4b30-8e52-8116dc2a01ff"}}
Step3: View Fleet information
Note: The term ‘Blue Water’ referred to here means at sea (including ports and coastal waters).
- From the home page, select the
Simulate Blue Watertile. Select one of the available fleet. As of now, only the North Pacific has fleet data:
The fleet panel lists the ships, their location and status and a map:
- Select one ship with the edit button. You will see the ship detail view:
This view contains information about the ship itself, it’s position at sea and the load. There is also an option to simulate a number of disaster scenarios that could play out at sea, however this functionality is not yet implemented.
There are currently three pre-defined scenarios, which will be implemented in the future:
- Fire affecting some containers
- Reefer down
- Ship experiencing conditions that cause reefers to exceed desired temperature.
This quickstart guide will be updated as the project evolves and new capability is added. If you have any issues or queries with this quickstart guide, please raise an issue in the github repo.