Skip to content

Commit 71bd439

Browse files
KuassimKuassim
committed
Architecture update
Architecture backend
1 parent 49b9c75 commit 71bd439

File tree

3 files changed

+744
-0
lines changed

3 files changed

+744
-0
lines changed

‎mtdrworkshop/backend/Readme.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Backend
2+
3+
## Introduction
4+
5+
In this lab, you will deploy the pre-built Helidon Java backend Docker image to OKE, then configure the API Gateway.
6+
7+
Estimated time: ~25-minutes.
8+
9+
### Objectives
10+
11+
* Set values for environment variables
12+
* Build and deploy the Docker image of the application
13+
* Deploy the image on the Oracle Kubernetes Engine (OKE)
14+
* Describe the steps for Undeploying
15+
* Configure the API Gateway
16+
* Test the backend application
17+
18+
### Prerequisites
19+
20+
This lab requires the completion of lab 1 and the provision of the OCI components.
21+
22+
### Understanding the Java/backend application
23+
24+
As with most React applications (https://reactjs.org/), this application uses remote APIs to handle data persistence. The backend implements 5 REST APIs including:
25+
- Retrieving the current list of todo items
26+
- Adding a new todo item
27+
- Finding a todo item by its id
28+
- Updating an existing todo item
29+
- Deleting a todo item.
30+
31+
The APIs are documented using Swagger @ http://130.61.67.158:8780/swagger-ui/#/
32+
33+
The backend is implemented using the following Java classes (under ./backend/src/...):
34+
- Main.java: starts and configure the main entry points.
35+
- ToDoItem.java: maps a Todo Item instance to/from JSON document
36+
- ToDoItemStorage.java: stores the Todo item in a persistent store i.e., the Oracle Autonomous database
37+
- ToDoListAppService.java: implements the Helidon service and exposes the REST APIs
38+
39+
![](images/Backend-APIs.png " ")
40+
41+
42+
## **STEP 1**: Set values for workshop environment variables
43+
44+
1. Set the root directory of the workshop
45+
```
46+
<copy>export MTDRWORKSHOP_LOCATION=~/mtdrworkshop</copy>
47+
```
48+
2. Run source addAndSourcePropertiesInBashrc.sh
49+
50+
The following command will set the values of environment variables in mtdrworkshop.properties and source ~/.bashrc
51+
52+
```
53+
<copy>cd $MTDRWORKSHOP_LOCATION; source addAndSourcePropertiesInBashrc.sh
54+
</copy>
55+
```
56+
57+
## **STEP 2**: Build and push the Docker images to the OCI Registry
58+
59+
1. Ensure that the "DOCKER_REGISTRY" variable is set
60+
61+
Example: `<region-key>.ocir.io/<object-storage-namespace>/<firstname.lastname>/<repo-name>`
62+
If the variable is not set or is an empty string, the push will fail (but the docker image will be built).
63+
64+
2. Make sure to be in backend/target/classes/wallet directory then execute
65+
```
66+
<copy>unzip ~/mtdrworkshop/setup-dev-environment/wallet.zip</copy>
67+
```
68+
69+
3. Pick mtdrb_tp service alias (see the list of aliases in
70+
./backend/target/classes/wallet/tnsnames.ora)
71+
72+
![](images/tnsnames-ora.png " ")
73+
74+
4. Edit ./backend/target/classes/application.yaml to set the database service and user password
75+
![](images/application-yaml.png " ")
76+
77+
5. Copy the edited ./backend/target/classes/application.yaml to ./backend/src/main/resources/application.yaml
78+
79+
6. Edit ./backend/src/main/java/com/oracle/todoapp/Main.java
80+
- Locate the following code fragment
81+
![](images/CORS-Main.png " ")
82+
- Replace `eu-frankfurt-1` in `"https://objectstorage.eu-frankfurt-1.oraclecloud.com"` by your region
83+
84+
- Save the file
85+
86+
7. Run `build.sh` script to build and push the
87+
microservices images into the repository
88+
89+
```
90+
<copy>cd $MTDRWORKSHOP_LOCATION/backend; ./build.sh</copy>
91+
```
92+
In a couple of minutes, you should have successfully built and pushed the images into the OCIR repository.
93+
94+
8. Check your container registry from the root compartment
95+
- Go to the Console, click the hamburger menu in the top-left corner and open
96+
**Developer Services > Container Registry**.
97+
98+
![](images/Registry-root-compart.png " ")
99+
100+
9. Mark Access as Public (if Private)
101+
(**Actions** > **Change to Public**):
102+
103+
![](images/Public-access.png " ")
104+
105+
## **STEP 3**: Deploy on Kubernetes and Check the Status
106+
107+
1. Run the `deploy.sh` script
108+
109+
```
110+
<copy>cd $MTDRWORKSHOP_LOCATION/backend; ./deploy.sh</copy>
111+
```
112+
113+
--> service/todolistapp-helidon-se-service created
114+
--> deployment.apps/todolistapp-helidon-se-deployment created
115+
116+
2. Check the status using the following commands
117+
$ kubectl get services
118+
119+
The following command returns the Kubernetes service of MyToDo application with a load balancer exposed through an external API
120+
```
121+
<copy>kubectl get services</copy>
122+
```
123+
124+
![](images/K8-service-Ext-IP.png " ")
125+
126+
3. $ kubectl get pods
127+
```
128+
<copy>kubectl get pods</copy>
129+
```
130+
131+
![](images/k8-pods.png " ")
132+
133+
5. Continuously tailing the log of one of the pods
134+
135+
$ kubectl logs -f <pod name>
136+
Example kubectl lgs -f todolistapp-helidon-se-deployment-7fd6dcb778-c9dbv
137+
138+
Returns:
139+
http://130.61.66.27/todolist
140+
141+
## **STEP 4**: UnDeploy (optional)
142+
143+
If you make changes to the image, you need to delete the service and the pods by running undeploy.sh then redo Steps 2 & 3.
144+
145+
1. Run the `undeploy.sh` script
146+
```
147+
<copy>cd $MTDRWORKSHOP_LOCATION/backend; ./undeploy.sh</copy>
148+
```
149+
2. Rebuild the image + Deploy + (Re)Configure the API Gateway
150+
151+
152+
## **STEP 5**: Configure the API Gateway
153+
154+
The API Gateway protects any RESTful service running on Container Engine for Kubernetes, Compute, or other endpoints through policy enforcement, metrics and logging.
155+
Rather than exposing the Helidon service directly, we will use the API Gateway to define cross-origin resource sharing (CORS).
156+
157+
1. From the hamburger menu navigate **Developer Services** > **API Management > Create Gateway**
158+
![](images/API-Gateway-menu.png " ")
159+
160+
2. Configure the basic info: name, compartment, VCN and Subnet
161+
- VCN: pick on of the vitual circuit network
162+
- Subnet pick the public subnet
163+
The click "Create"
164+
![](images/Basic-gateway.png " ")
165+
166+
3. Click on Todolist gateway
167+
![](images/Gateway.png " ")
168+
169+
4. Click on Deployments
170+
![](images/Deployment-menu.png " ")
171+
172+
5. Create a todolist deployment
173+
![](images/Deployment.png " ")
174+
175+
176+
6. Configure Cross-origin resource sharing (CORS) policies.
177+
- CORS is a security mechanism that will prevent running application loaded from origin A from using resources from another origin B.
178+
- Allowed Origins: is the list of all servers (origins) that are allowed to access the API deployment typically your Kubernetes cluster IP.
179+
- Allowed methods: GET, PUT, DELETE, POST, OPTIONS are all needed.
180+
![](images/Origins-Methods.png " ")
181+
182+
7. Configure the Headers
183+
![](images/Headers.png " ")
184+
185+
8. Configure the routes: we will define two routes:
186+
- /todolist for the first two APIs: GET, POST and OPTIONS
187+
![](images/Route-1.png " ")
188+
189+
- /todolist/{id} for the remaining three APIs: (GET, PUT and DELETE)
190+
![](images/Route-2.png " ")
191+
192+
193+
## **STEP 6**: Testing the backend application through the API Gateway
194+
195+
1. Navigate to the newly create Gateway Deployment Detail an copy the endpoint
196+
![](images/Gateway-endpoint.png " ")
197+
198+
2. Testing through the API Gateway endpoint
199+
postfix the gateway endpoint with "/todolist" as shown in the image below
200+
![](images/Backend-Testing.png " ")
201+
202+
It should display the Todo Item(s) in the TodoItem table. At least the row you have created in Part I.
203+
204+
Congratulations, you have completed lab 2; you may now [proceed to the next lab](#next).
205+
206+
## Acknowledgements
207+
208+
* **Author** - - Kuassi Mensah, Dir. Product Management, Java Database Access
209+
* **Contributors** - Jean de Lavarene, Sr. Director of Development, JDBC/UCP
210+
* **Last Updated By/Date** - Kuassi Mensah, Database Product Management, April 2021

‎mtdrworkshop/frontend/Readme.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Frontend (ReactJS)
2+
3+
## Introduction
4+
5+
In this lab you will deploy a pre-built ReactJS application locally then build it for production an host it on the Oracle Cloud Infrastucture.
6+
7+
Estimated Lab Time: 15-minutes
8+
9+
### Objectives
10+
11+
In this lab, you will:
12+
- Clone the workshop git repository on your laptop
13+
- Set the API Gateway endpoint
14+
- Run the ReactJS frontend code in Dev Mode then Build for Production
15+
- Host the production build on the Oracle Cloud's object storage
16+
17+
### Understanding the ReactJS application
18+
19+
The application is simple; it uses Functional Components with State Hooks for managing states. There is a main component called "App" which renders another component called "NewItem" and two tables of todo items: the active ones and the already done ones. The "NewItem" component displays the text field to add a new item.
20+
21+
The App component includes the "items" state ([]) which contains the list of todo items. When setItems is called with a new array of items the component will re-render.
22+
23+
The App component also maintains the following states:
24+
25+
- "isLoading" is true when waiting for the backend to return the list of items.We use this state to display a spinning wheel while loading.
26+
27+
- "isInserting" is true when waiting for the backend to process a new insert item. The "Add" button will display a spinning wheel during this time.
28+
29+
- "error" stores the error messages received during the API calls.
30+
31+
The index.css file contains all the styles for the application.
32+
33+
### Prerequisites
34+
35+
1. This lab requires the completion of lab 1 and 2
36+
37+
2. You will be using the npm command, make sure it is installed
38+
39+
```
40+
<copy>npm --version</copy>
41+
```
42+
43+
if not please install Node for your laptop, using the following
44+
link: `https://bit.ly/3evGlEo`.
45+
46+
3. The lab requires also Go lang.
47+
48+
"go version" -> `go version go1.15.2 darwin/amd64`
49+
50+
```
51+
<copy>go version</copy>
52+
```
53+
If not installed, please install Go (see https://golang.org/doc/)
54+
55+
## **STEP 1**: Configure API.js
56+
57+
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
58+
59+
1. clone again the git repository to a directory on your laptop (we only need the front end in this lab)
60+
```
61+
<copy>git clone https://github.com/oracle/oci-react-samples/mtdrworkshop.git</copy>
62+
```
63+
64+
2. cd frontend
65+
66+
3. Run the following npm commands to install the required packages
67+
68+
```
69+
<copy>npm install --save typescript</copy>
70+
```
71+
```
72+
<copy>npm install</copy>
73+
```
74+
- In case of errors, try the following command
75+
```
76+
<copy>npm audit fix --force</copy>
77+
```
78+
- Ideally, npm -version should return > 6.14.x AND Node version > 14.16.x
79+
If npm version < 6.14.x then install the latest Node using
80+
https://bit.ly/3evGlEo
81+
82+
4. Update API_LIST in API.js
83+
84+
- Make sure to be in frontend/src directory
85+
```
86+
<copy>cd frontend/src</copy>
87+
```
88+
- In the Cloud console, navigate to **Developer Services > API Management**
89+
- Click on your Gateway and go to Deployment
90+
- Copy the Endpoint
91+
- Paste the endpoint as the value of API_LIST and append "/todolist"
92+
93+
Example
94+
const API_LIST = 'https://xxxxxxxxxx.apigateway.eu-frankfurt-1.oci.customer-oci.com/todolist';
95+
96+
- Save the modified API.js file
97+
98+
## **STEP 2**: Run in Dev Mode then Build for Production
99+
100+
1. In the project directory, run the app in the development mode <br />
101+
102+
```
103+
<copy>npm start</copy>
104+
```
105+
106+
2. Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
107+
108+
3. The page will reload if you make edits.<br />
109+
You will also see any lint errors in the console.
110+
111+
4. Cancel the developer mode execution and build the app for production to the `build` folder.<br />
112+
113+
- Issue "Ctrl-c" to cancel the developer mode executions
114+
115+
- Execute npm run build
116+
```
117+
<copy>npm run build</copy>
118+
```
119+
It correctly bundles React in production mode (into the build folder) and optimizes the build for the best performance.
120+
121+
![](images/Run-build.png " ")
122+
123+
The build is minified and the filenames include the hashes.<br />
124+
Your app is ready to be deployed!
125+
126+
See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
127+
128+
## **STEP 3**: Hosting on the Oracle Cloud's object storage
129+
130+
1. Open up the hamburger menu in the top-left corner of the Console and select
131+
**Object Storage > Object Storage**.
132+
133+
- Create the 'mtdrworkshop' bucket
134+
135+
2. Install the Staci utility for copying directories to OCI object storage
136+
bucket with folder hierarchies
137+
138+
- git clone https://github.com/maxjahn/staci.git
139+
140+
```
141+
<copy>git clone https://github.com/maxjahn/staci.git</copy>
142+
```
143+
144+
- cd staci
145+
146+
```
147+
<copy>cd staci</copy>
148+
```
149+
150+
- go get -d
151+
152+
```
153+
<copy>go get -d</copy>
154+
```
155+
156+
- go build
157+
158+
```
159+
<copy>go build</copy>
160+
```
161+
162+
3. Upload a static build into the bucket, using the staci binary
163+
164+
```
165+
<copy>./staci/staci -source build -target mtdrworkshop</copy>
166+
```
167+
168+
- The application is visible in the 'mtdrworkshop' bucket of your tenancy
169+
170+
- Click on the index.html object and copy the URL of the index object
171+
172+
![](images/bucket-index.png " ")
173+
174+
- You may now run the application from Object store, using the URL of the index that you've copied above.
175+
176+
![](images/MyToDo.png " ")
177+
178+
Congratulations for completing the entire lab!!
179+
180+
## Acknowledgements
181+
182+
* **Author** - - Kuassi Mensah, Dir. Product Management, Java Database Access
183+
* **Contributors** - Jean de Lavarene, Sr. Director of Development, JDBC/UCP
184+
* **Last Updated By/Date** - Kuassi Mensah, Database Product Management, April 2021

0 commit comments

Comments
 (0)