Skip to content
This repository was archived by the owner on May 30, 2024. It is now read-only.

Commit 2dfa899

Browse files
Gaurav-RamakrishnaGaurav-Ramakrishna
committed
update the documentation
1 parent f0b4744 commit 2dfa899

File tree

3 files changed

+310
-239
lines changed

3 files changed

+310
-239
lines changed

‎README.md‎

Lines changed: 37 additions & 239 deletions
Original file line numberDiff line numberDiff line change
@@ -10,266 +10,64 @@ Liquid Prep backend service exposes Cloud Functions API endpoints for Liquid Pre
1010
2. **[IBM Cloudant DB](https://cloud.ibm.com/docs/Cloudant):** <br>
1111
- The Cloudant DB acts a storage for all the crop data which will explained in the **IBM Cloudant** section.
1212

13-
Currently the backend service is deployed and hosted on IBM Cloud Liquid Prep's account.
14-
You can also setup and deploy the Liquid Prep backend service on your own IBM Cloud account.
13+
## Setup and Deploy Backend in IBM Cloud
1514

16-
Instructions on how to setup, configure and deploy the backend service is as follows:
15+
The first step is to setup and configure Cloud Functions and Cloudant DB in IBM Cloud. Then deploy the backend service on IBM Cloud Functions.
1716

18-
## Pre-requisites
17+
Please refer to the [IBM Cloud Setup and Deployment Document](SETUP.md) to get started.
1918

20-
1. IBM Cloud account:
21-
22-
- [Create an IBM Cloud account](https://cloud.ibm.com/registration)
23-
- [Install IBM Cloud CLI](https://cloud.ibm.com/docs/cli?topic=cloud-cli-getting-started)
24-
- [Setup the Cloud Functions CLI plug-in](https://cloud.ibm.com/docs/openwhisk?topic=openwhisk-cli_install)
25-
- **Create IAM API key**;
26-
27-
- Login to IBM Cloud account.
28-
- Click on **Manage** tab on top right of the IBM Cloud dashboard. And click on **Access (IAM)** option to open **Manage access and users** dashboard.
29-
- Select **API keys** option on left pane of the dashboard.
30-
- Select **Create an IBM Cloud API key** button on right of the **API keys** dashboard.
31-
<p align="left">
32-
<img src="../images/backend/IAM/iamKey.PNG" width ="30%" height="30%">
33-
</p>
34-
35-
- Enter an API key name and description. Example,
36-
<p align="left">
37-
<img src="../images/backend/IAM/createIAMApikey.PNG" width ="30%" height="30%">
38-
</p>
39-
40-
- An IAM API key will be created, copy and/or download the key and secure it safely.
41-
**NOTE:** This IAM API key is required later for Liquid Prep project deployment and IBM Cloud CLI login. Please copy/download and store it in a secure place. If the IAM API key is **NOT** copied/downloaded and stored in secure place, you will have to create new IAM API key.
42-
43-
- **Create Resource Group**;
44-
45-
- Click on **Manage** tab on top right of the IBM Cloud dashboard. And click on **Account** option to open **Account** dashboard.
46-
- Select **Resource groups** option on the left panel of the dashboard. Usually a **Default** resource group will be created when a cloud account is created. If not a new Resource group can be created by clicking on the **Create** button on the right of the **Resource groups** dashboard.
47-
<p align="left">
48-
<img src="../images/backend/account/resourceGrp.PNG" width ="30%" height="30%">
49-
</p>
50-
51-
- **Create Cloud Foundry Organization**;
52-
53-
- From the **Account** dashboard, select **Cloud Foundry orgs** option on the left pane to open **Cloud Foundry Orgs** dashboard.
54-
- Click on **Create** on the top right of the dashboard to create new Organization. If an organization already exists, you can use the same.
55-
<p align="left">
56-
<img src="../images/backend/account/organization.PNG" width ="30%" height="30%">
57-
</p>
58-
59-
- **Create Space**;
60-
- From the **Cloud Foundry Orgs** dashboard, click on the Name of the organization to open the **Space** tab for the organization.
61-
- Click on the **Add a space** button the top right of the dashboard to create new Space. If a space already exists, you can use the same.
62-
<p align="left">
63-
<img src="../images/backend/account/space.PNG" width ="30%" height="30%">
64-
</p>
65-
66-
2. Git:
67-
68-
- [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git/)
69-
- [Configure Git](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)
70-
- [Git account setup and configuration](https://git-scm.com/book/en/v2/GitHub-Account-Setup-and-Configuration)
71-
72-
3. Liquid Prep project:
73-
74-
- [Git clone Liquid Prep project](https://github.com/Liquid-Prep/Liquid-Prep)
75-
76-
4. The Weather Company API Key:
77-
78-
- [Register and subscribe The Weather Company service API key](https://www.ibm.com/products/weather-company-data-packages/details)
79-
80-
5. Node and NPM:
81-
- [Install Node and NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
82-
83-
## IBM Cloud Functions
84-
85-
1. Create a new IBM cloud account. If you already have an account, please log in to account.
86-
2. Select **IBM Cloud Functions** icon on left the pane of the IBM Cloud account dashboard <br>
87-
<p align="left">
88-
<img src="../images/backend/cloudFunctions/dashboard_cloudFunctions.PNG" width ="30%" height="30%">
89-
</p>
90-
Or you can search for **Functions** in search bar and select **Functions**.
91-
<p align="left">
92-
<img src="../images/backend/cloudFunctions/searchCF.PNG" width ="30%" height="30%">
93-
</p>
94-
3. Select **Actions** option on the left pane of **IBM Cloud Functions** dashboard.
95-
<p align="left">
96-
<img src="../images/backend/cloudFunctions/actionsCF.PNG" width ="30%" height="30%">
97-
</p>
98-
4. Create new Actions by clicking the **Create** on top right of the dashboard, enter Action Name as **liquid-prep-action**. Create new Package **liquidPrep**. Select **Node.js 12** as Runtime.
99-
<p align="left">
100-
<img src="../images/backend/cloudFunctions/createActionCF.PNG" width ="30%" height="30%">
101-
</p>
102-
5. Go back to **IBM Cloud Functions** dashboard and select **APIs** option on the left pane.
103-
<p align="left">
104-
<img src="../images/backend/cloudFunctions/api_cloudFunctions.PNG" width ="30%" height="30%">
105-
</p>
106-
6. Select **Create API** option on top right of the dashboard, enter API name as **liquidPrep-cf-api**. Let the **Base path for API** be default **/liquidPrep-cf-api**. Let other settings be default values, unless other specific entries are required. Scroll down the page and select **Create**.
107-
<p align="left">
108-
<img src="../images/backend/cloudFunctions/createAPI_CF.PNG" width ="30%" height="30%">
109-
</p>
110-
7. Once API is created, select the API **liquidPrep-cf-api**, select **Manage Sharing and Keys** on the left pane of the API dashboard. Enable **Include API in organization-level Shared APIs view**.
111-
<p align="left">
112-
<img src="../images/backend/cloudFunctions/shareAPI_CF.PNG" width ="30%" height="30%">
113-
</p>
114-
115-
## IBM Cloudant
116-
117-
1. Enter **Cloudant** in the IBM Cloud search bar and select **Cloudant**.
118-
<p align="left">
119-
<img src="../images/backend/cloudant/searchCloudant.PNG" width ="30%" height="30%">
120-
</p>
121-
1. Under **Select an environment** section, enter Instance Name as **Cloudant-liquidPrep**.
122-
1. Select **IAM** as Authentication method.
123-
1. Select a suitable pricing Plan – Lite, Standard and Standard on Transaction Engine.
124-
<p align="left">
125-
<img src="../images/backend/cloudant/configureCloudant.PNG" width ="30%" height="30%">
126-
</p>
127-
1. Select **Create** on the bottom right pane of Cloudant dashboard. After you click **Create**, a message displays to say that the instance is being provisioned, which returns you to the Resource list. From the Resource list, you see the status for your instance is, **Provision in progress.**
128-
<p align="left">
129-
<img src="../images/backend/cloudant/activeCloudant.PNG" width ="30%" height="30%">
130-
</p>
131-
1. When status of the instance changes to **Active**, click the **Cloudant-liquidPrep** instance and select **Service Credentials** tab on left pane of dashboard.
132-
1. Select **New Credential**, enter Name as **liquid-prep** and Role as **Manager**. A service credential will be created.
133-
<p align="left">
134-
<img src="../images/backend/cloudant/serviceCredsCloudant.PNG" width ="30%" height="30%">
135-
</p>
136-
1. Select **Manage** tab on the left pane and select **Launch Dashboard** on the top right of the page. It will launch a Cloudant dashboard to create new database.
137-
1. On the Databases page, select **Create Database** on the top right of the Cloudant dashboard.
138-
1. Enter Database name as **liquid-prep-crops**. Select the Partitioning option as **Non-partitioned**. And click on **Create** button at the bottom.
139-
<p align="left">
140-
<img src="../images/backend/cloudant/createDBCloudant.PNG" width ="15%" height="30%">
141-
</p>
142-
1. **liquid-prep-crops** database will be created and listed in Databases page.
143-
1. Select **liquid-prep-crops** and click on **Create Document** on top right of the page. A document with auto generated **\_id** key will open.
144-
<p align="left">
145-
<img src="../images/backend/cloudant/createDoc_cloudant.PNG" width ="30%" height="30%">
146-
</p>
147-
1. Go to Liquid Prep project directory `~/Liquid-Prep/backend/resources/crops`. Open each crop document, copy the contents in the document and paste it in the **New Document** that was opened in **liquid-prep-crops** database and click **Create Document** button. <br>
148-
Example for Corn crop;
149-
<p align="left">
150-
<img src="../images/backend/cloudant/createDoc_cloudant_corn.PNG" width ="30%" height="30%">
151-
</p>
152-
Corn document will be created and listed in **liquid-prep-crops** database.
153-
<p align="left">
154-
<img src="../images/backend/cloudant/liquidPrep_cloudant_cropsList.PNG" width ="30%" height="30%">
155-
</p>
156-
1. Similarly, repeat step 13 for all the other crops document.
157-
158-
## Deploy Liquid Prep Backend Service
159-
160-
After configuring IBM Cloud Functions and Cloudant DB, the Liquid Prep backend project needs to built, bundled and deployed to IBM Cloud Functions to expose Cloud Functions API for Liquid Prep application. <br>
161-
162-
1. Go to Liquid Prep project directory `~/Liquid-Prep/backend/liquid-prep-cf` and create **.env** file.
163-
2. Add following entries to the **.env** file;
164-
165-
```
166-
IAM_API_KEY=xxxxxx
167-
CLOUD_FUNCTIONS_URL=https://xxxxxx.appdomain.cloud/liquidprep-cf-api
168-
CLOUDANT_DB_URL=https://xxxxxx-bluemix.cloudant.com/
169-
CLOUDANT_DB_NAME=liquid-prep-crops
170-
WEATHER_API_KEY=xxxxxxxxxx
171-
```
172-
173-
where the entries should be filled out as follows:
174-
175-
**IAM_API_KEY:** <br>
176-
It is the API key created at the beginning when an IBM Cloud account is created. Please refer to the **Pre-requisites** section on how to create/obtain the IAM API key.
177-
178-
**CLOUD_FUNCTIONS_URL:** <br>
179-
- Go to IBM Cloud dashboard.
180-
- Click on the **Navigation Menu** on the top left corner of the dashboard.
181-
- Select **API Management** option.
182-
<p align="left">
183-
<img src="../images/backend/envEntries/apiManage.PNG" width ="30%" height="30%">
184-
</p>
185-
186-
- Select **Shared APIs** in **API Management** dashboard.
187-
- The **Route** value in **Shared APIs** dashboard is the **CLOUD_FUNCTIONS_URL** value.
188-
<p align="left">
189-
<img src="../images/backend/envEntries/sharedApi.PNG" width ="30%" height="30%">
190-
</p>
191-
192-
***CLOUDANT_DB_NAME: liquid-prep-crops*** <br>
193-
It is the Cloudant database name which was created to add the crop documents. <br>
194-
195-
***CLOUDANT_DB_URL:*** <br>
196-
The Cloudant DB URL can be obtained from its **Manage** dashboard.
197-
- Go to IBM CLoud dashboard.
198-
- Click on the **Navigation Menu** on the top left corner of the dashboard.
199-
- Select **Resource List** option.
200-
- Select **Cloudant-liquidPrep** instance under **Services** in **Resource list** dashboard.
201-
<p align="left">
202-
<img src="../images/backend/envEntries/cloudantService.PNG" width ="30%" height="30%">
203-
</p>
204-
205-
- The **External Endpoint (preferred)** value is the **CLOUDANT_DB_URL** value.
206-
<p align="left">
207-
<img src="../images/backend/envEntries/cloudantEndpoint.PNG" width ="30%" height="30%">
208-
</p>
209-
210-
***WEATHER_API_KEY:*** <br>
211-
The Weather API key is obtained by subscribing to The Weather Company API services. https://www.ibm.com/products/weather-company-data-packages/details
212-
213-
1. Open command terminal and execute `npm install` in project directories `~/Liquid-Prep/backend/liquid-prep-cf` and `~/Liquid-Prep/backend/common`.
214-
2. Log into IBM Cloud account from command terminal with **ibmcloud** CLI. Execute the login command, <br>
215-
`ibmcloud login --apikey <IAM API key> -g <Resource Group> -o <organisation> -s <space> -r <region>` <br>
216-
217-
- **--apikey**: <br>
218-
It is the **API key** created at the beginning when an IBM Cloud account is created. Please refer to the **Pre-requisites --> IBM Cloud account --> Create IAM API key** section on how to create/obtain the IAM API key.
219-
220-
- **-g**: <br>
221-
It is the **Resource group** of the cloud account. Usually a **Default** resource group will be created. If not you can create a new resource group and enter. <br>
222-
Please refer to the **Pre-requisites --> IBM Cloud account --> Create Resource Group** section on how to create/obtain the Resource group.
223-
224-
- **-o**: <br>
225-
It is the **Cloud Foundry Organization** of the cloud account. Please refer to the **Pre-requisites --> IBM Cloud account --> Create Cloud Foundry Organization** section on how to create/obtain the Cloud Foundry Organization.
226-
227-
- **-s**: <br>
228-
It is the **Space** in the **Cloud Foundry Organization** of the cloud account. Please refer to the **Pre-requisites --> IBM Cloud account --> Create Space** section on how to create/obtain the Space.
229-
230-
- **-r**: <br>
231-
It is the **Region** of the cloud account. Region can be obtained in the selected **Cloud Foundry Organization** dashboard beside the **Space** Name.
232-
<p align="left">
233-
<img src="../images/backend/account/space.PNG" width ="30%" height="30%">
234-
</p>
19+
## Liquid Prep APIs
23520

236-
3. Navigate to project directory `~/Liquid-Prep/backend/liquid-prep-cf` from command terminal and execute `npm run deploy-dev-api`.
21+
Once the backend service is deployed, you can test the APIs if they are working as expected. You can test the APIs by simply calling them in any browser (Chrome, Firefox, Edge) or using CURL command or API clients like [Postman](https://www.postman.com/).
23722

238-
Once the deployment is successful, go to IBM Cloud Functions dashboard, select **Actions** tab on the left pane and you can see **liquid-prep-action** instance in the **Actions** dashboard.
23+
You will have to first capture the **API Host URL** from the API Management Dashboard in IBM Cloud.
23924

240-
<p align="left">
241-
<img src="../images/backend/cloudFunctions/liquidPrep-Actions-CF.PNG" width ="30%" height="30%">
25+
<p align="middle">
26+
<img src="images/shareAPIEndpoint.PNG" width ="30%" height="30%">
24227
</p>
24328

244-
## Liquid Prep APIs
29+
The backend currently supports 3 APIs;
24530

246-
The backend service is deployed in Liquid Prep cloud account and the APIs can be tested by executing them in any browser URL path.
31+
1. **GET-WEATHER-INFO:** <br>
32+
Get weather information for a location.
24733

248-
1. **GET-WEATHER-INFO:**
249-
Get weather information for a location. <br>
250-
https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_weather_info?geoCode=<lat,long>&units=<metric/imperical> <br>
34+
```text
35+
https://<API Host URL>/liquidprep-cf-api/get_weather_info?geoCode=<lat,long>&units=<metric/imperical>
36+
```
25137

25238
**Params:** <br>
25339

25440
- **geoCode**: Geo-coordinates (latitude, longitude) of location.
25541
- **units**: metric (e) or imperial (m)
25642

25743
**Example:** <br>
258-
Get weather information for geo-coordinates latitude 42.359, longitude 71.068 and units in metrics (e). <br>
259-
https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_weather_info?geoCode=42.359,-71.068&units=e
44+
Get weather information for geo-coordinates latitude 42.359, longitude 71.068 and units in metrics (e).
45+
46+
```text
47+
https://<API Host URL>/liquidprep-cf-api/get_weather_info?geoCode=42.359,-71.068&units=e
48+
```
49+
50+
2. **GET-CROP-LIST:**<br>
51+
Get list of all the crop names and their IDs supported by Liquid Prep. <br>
52+
53+
```text
54+
https://<API Host URL>/liquidprep-cf-api/get_crop_list
55+
```
56+
57+
3. **GET-CROP-INFO:**<br>
58+
Get a crop information supported by Liquid Prep.
26059

261-
2. **GET-CROP-INFO:**
262-
Get crop information for a particular crop supported by Liquid Prep. <br>
263-
https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_crop_info?id=<\_id> <br>
60+
```text
61+
https://<API Host URL>/liquidprep-cf-api/get_crop_info?id=<\_id>
62+
```
26463

26564
**Params:** <br>
26665

267-
- **id**: Id is the unique identity number assigned for the crop and can be obtained from list of supported crops in https://github.com/Liquid-Prep/Liquid-Prep/tree/master/backend/resources/crops <br>
66+
- **id**: It is the unique identity number assigned for the crop and can be obtained from list of supported crops by executing the **GET-CROP-LIST** API <br>
26867

26968
**Example:** <br>
270-
Get crop information for Corn. <br>
271-
https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_crop_info?name=1
69+
Get crop information for Corn.
27270

273-
3. **GET-CROP-INFO:**
274-
Get list of all crop names supported by Liquid Prep. <br>
275-
https://service.us.apiconnect.ibmcloud.com/gws/apigateway/api/96fd655207897b11587cfcf2b3f58f6e0792f788cf2a04daa79b53fc3d4efb32/liquidprep-cf-api/get_crop_list <br>
71+
```text
72+
https://<API Host URL>/liquidprep-cf-api/get_crop_info?id=1
73+
```

0 commit comments

Comments
 (0)