Tenki (天気) Channel :cloud:

Tenki Channel is a tech demo that puts Kogito, Camel, Quarkus and OpenShift together to showcase some examples using those components.

Tenki (天気) in Japanese means weather. :-D

Rain Forecast - Is it gonna rain? :umbrella:

In this use case we have two back-end services working together to answer a simple question: "Is it gonna rain on my location?".

The first service, Rain Forecast Process uses the process automation framework, Kogito, to automate a forecast process that will call the Weather API Gateway. Based on the weather forecast results, calculated by a decision rule, the process will give you the answer.

The Weather API Gateway is a Camel service that hides the external weather service and exposes the domain data that we're interested in. The gateway implements (in a certain level) the API Gateway pattern.

Both back-end services are backed by the Quarkus framework. This means that you can run in native code in the cloud.

There is also a front-end UI which displays in a friendly way for users and shows one possible to consume the back-end services.

Quickstart

Works on OCP 3.11 and 4.x.
Requires deploy of three pieces: two back-end services (kogito and camel) and one front-end UI.
Requires a free account at openweathermap. Grab your API Key to use on the demo deployment.
Requires a free account at Yahoo Weather API. Add a new application in the Yahoo Developer portal to grab your keys.
Quickest way to have this demo up and running is to deploy on OpenShift using the provided templates. You won't have the full experience though. Or, you can have the experience of deploying it with Kogito Operator (or using the Kogito CLI).

Deploy the back-end via template

# clone this repo
$ git clone https://github.com/ricardozanini/tenkichannel.git
$ cd tenkichannel
$ oc new-project tenkichannel
$ oc create -f openshift/rain-forecast/templates/rain-forecast-backend.yaml
# grab your API key on https://openweathermap.org/api
$ oc new-app --template=rain-forecast-demo-backend -p NAMESPACE=tenkichannel -p OPENWEATHER_API_KEY=<your-api-key> -p YAHOO_API_ID=<your-id> -p YAHOO_CLIENT_ID=<client-id> -p YAHOO_CLIENT_SECRET=<client-secret>
# create the UI template
$ oc create -f openshift/rain-forecast/templates/rain-forecast-ui.yaml
# create the UI application using as parameter the rain-forecast route that were generated in the above section
$ oc new-app --template=rain-forecast-demo-ui -p BACKEND_ROUTE=<service-route>

Deploy the back-end with Kogito Operator

Install Kogito Operator and then:

# clone this repo
$ git clone https://github.com/ricardozanini/tenkichannel.git
$ oc new-project tenkichannel
# Deploy Kogito App
$ oc create -f openshift/rain-forecast/operator/rain-forecast-kogitoapp.yaml
# Deploy Camel Service (REPLACE YOUR KEYS!!!!)
$ oc new-app https://github.com/ricardozanini/tenkichannel --name=weather-api-gateway --context-dir=weather-api-gateway -e JAVA_OPTIONS="-Dorg.tenkichannel.weather.api.gateway.openweathermap.api_key=<your_api_key> -Dorg.tenkichannel.weather.api.gateway.yahooweather.id=<yahoo_api_id> -Dorg.tenkichannel.weather.api.gateway.yahooweather.consumerKey=<yahoo_consumer_key> -Dorg.tenkichannel.weather.api.gateway.yahooweather.consumerSecret=<yahoo_consume_secret>" --docker-image=docker.io/fabric8/s2i-java:latest-java11 -l forecast=service

Deploy the front-end

Set the BACKEND_ROUTE variable with the route of your rain-forecast service i.e. https://rain-forecast-tenkichannel.apps.your-cluster.com (please remove the last backslash)

# create the UI template
$ oc create -f openshift/rain-forecast/templates/rain-forecast-ui.yaml
# create the UI application using as parameter the rain-forecast route that were generated in the above section
$ oc new-app --template=rain-forecast-demo-ui -p BACKEND_ROUTE=<service-route>

Access the front-end application using its route.

Detailed Instructions

Main Pre-reqs

You need to create a free account on openweathermap, login and copy the API Key to use on the demo deployment;
You also need an Yahoo Developer account for the Yahoo Weather API;
oc client available (in case you want to deploy on Openshift);

Open Weather API

You will need an API Key on Open Weather. To get it follow these steps:

Create a free account and Log in
Go to API Keys menu and you will be able to see your default Key (or add other keys).

Running locally

To make both Kogito and Camel services work locally, read the guides (here and here) and have both services up and running. You should call the Rain Forecast Process at the rainforecast endpoint to see it in action.

Deploying on OpenShift ⭕️

You should either use templates OR the Kogito Operator to deploy the Rain Forecast Application.

Deploy using templates: The quicker method to have the demo up and running. It takes the pre built images from Quay and deploy them into your cluster.
Deploy using Kogito Operator: Experience how it is to deploy and use the Kogito Operator to deliver an application. It builds the application for you from this master branch. It's worth taking a look to get your hands dirty on the operator way of doing things on OpenShift.

This demo runs on OCP 3.11 and 4.x.

Option 1: Using Templates

To deploy the Rain Forecast demo on your OpenShift cluster, follow these steps:

# clone this repo
git clone https://github.com/ricardozanini/tenkichannel.git
$ cd tenkichannel
$ oc new-project tenkichannel
$ oc create -f openshift/rain-forecast/templates/rain-forecast-backend.yaml
# grab your API key on https://openweathermap.org/api
$ oc new-app --template=rain-forecast-demo-backend -p NAMESPACE=tenkichannel -p OPENWEATHER_API_KEY=<your-api-key> -p YAHOO_API_ID=<your-id> -p YAHOO_CLIENT_ID=<client-id> -p YAHOO_CLIENT_SECRET=<client-secret>

Then, you can see the route to access the process:

$ oc get route

NAME            HOST/PORT                                                           PATH   SERVICES        PORT       TERMINATION   WILDCARD
rain-forecast   rain-forecast-tenkichannel.apps.your-cluster.com                           rain-forecast   8080-tcp    edge         None

You can see your service swagger api running i.e. at /swagger-ui

See more details about how to use it at the Rain Forecast README doc.

Option 2: Using the Kogito Operator/CLI

Deploying using those templates it's easy to get the application working right away since we used pre built images, but in the real world you'll have to build (no pun intended) your way in.

That's why we have the Kogito Operator to do the hard job for you.

Install the Kogito Operator in your cluster either via CLI or Using Openshift OperatorHub.
Now you can deploy the Rain Forecast application with a CR:

$ oc new-project tenkichannel
$ oc create -f openshift/rain-forecast/operator/rain-forecast-kogitoapp.yaml

Using Kogito CLI

If you're feeling lazy, let the Kogito CLI deploy the operator (only on 0.5.0+ versions) and the application for you.

Install the Kogito CLI
Follow these steps to deploy the Kogito app using Kogito CLI:

$ kogito new-project tenkichannel
$ kogito deploy rain-forecast https://github.com/ricardozanini/tenkichannel --context-dir=rain-forecast-process -e NAMESPACE=tenkichannel -p tenkichannel

Edit the deployed route to use TLS since we're going to need secure connections in our demo. You can get the route with:

$ oc describe kogitoapp/rain-forecast | grep Route:
  Route:  https://rain-forecast-tenkichannel.mycluster.com

Use the new-app command from oc client to deploy camel service. (The Weather API Gateway is not a Kogito Service, so you can't use the operator to deploy it. Instead, u)

$ oc new-app https://github.com/ricardozanini/tenkichannel --name=weather-api-gateway --context-dir=weather-api-gateway -e JAVA_OPTIONS="-Dorg.tenkichannel.weather.api.gateway.openweathermap.api_key=<your_api_key> -Dorg.tenkichannel.weather.api.gateway.yahooweather.id=<yahoo_api_id> -Dorg.tenkichannel.weather.api.gateway.yahooweather.consumerKey=<yahoo_consumer_key> -Dorg.tenkichannel.weather.api.gateway.yahooweather.consumerSecret=<yahoo_consume_secret>" --docker-image=docker.io/fabric8/s2i-java:latest-java11 -l forecast=service

Deploying the User Interface

No matter the way you decided to deploy the Rain Forecast application backend services, you can use the UI to have the full demo experience. After installing the backend and playing with the API, it's time to have some fun with the UI.

You'll need the Rain Forecast Process route url. So, if you still don't have the backend services installed, go back to the previous steps and deploy them.
Once back-end services are up and running, run the commands bellow to install the UI. Replace the BACKEND_ROUTE with your application route (i.e. https://rain-forecast-tenkichannel.apps.your-cluster.com)

# create the UI template
$ oc create -f openshift/rain-forecast/templates/rain-forecast-ui.yaml
# create the UI application using as parameter the rain-forecast route that were generated in the above section
$ oc new-app --template=rain-forecast-demo-ui -p BACKEND_ROUTE=<your-app-route>

You should see the build spinning and in a couple minutes your application will be ready for use.

If you're running on a development environment, chances are that you're using self signed certificates. If this is the case, try to access the backend route at least once to have your browser to trust in your certificate.

Access the application using the new route, allow the browser to read your location and have fun!

Contributing

This is a work in progress and mainly used for presentations and general demos. If you see something wrong, please don't hesitate and send us a PR or file a issue in this repo. :)

ricardozanini / tenkichannel

readme