Architecture update

Architecture backend

mtdrworkshop/backend/Readme.md

@@ -0,0 +1,210 @@
+# Backend
+
+## Introduction
+
+In this lab, you will deploy the pre-built Helidon Java backend Docker image to OKE, then configure the API Gateway.
+
+Estimated time: ~25-minutes.
+
+### Objectives
+
+* Set values for environment variables
+* Build and deploy the Docker image of the application
+* Deploy the image on the Oracle Kubernetes Engine (OKE)
+* Describe the steps for Undeploying
+* Configure the API Gateway
+* Test the backend application
+
+### Prerequisites
+
+This lab requires the completion of lab 1 and the provision of the OCI components.
+
+### Understanding the Java/backend application
+
+As with most React applications (https://reactjs.org/), this application uses remote APIs to handle data persistence. The backend implements 5 REST APIs including:
+- Retrieving the current list of todo items
+- Adding a new todo item
+- Finding a todo item by its id
+- Updating an existing todo item
+- Deleting a todo item.
+
+The APIs are documented using Swagger @ http://130.61.67.158:8780/swagger-ui/#/
+
+The backend is implemented using the following Java classes (under ./backend/src/...):   
+- Main.java: starts and configure the main entry points.
+- ToDoItem.java: maps a Todo Item instance to/from JSON  document
+- ToDoItemStorage.java: stores the Todo item in a persistent store i.e., the Oracle Autonomous database
+- ToDoListAppService.java: implements the Helidon service and exposes the REST APIs
+
+  ![](images/Backend-APIs.png " ")
+
+
+## **STEP 1**: Set values for workshop environment variables
+
+1. Set the root directory of the workshop
+  ```
+  <copy>export MTDRWORKSHOP_LOCATION=~/mtdrworkshop</copy>
+  ```
+2. Run source addAndSourcePropertiesInBashrc.sh
+
+The following command will set the values of environment variables in mtdrworkshop.properties and source ~/.bashrc
+
+  ```
+  <copy>cd $MTDRWORKSHOP_LOCATION; source addAndSourcePropertiesInBashrc.sh
+ </copy>
+ ```
+
+## **STEP 2**: Build and push the Docker images to the OCI Registry
+
+1. Ensure that the "DOCKER_REGISTRY" variable is set
+
+ Example: `<region-key>.ocir.io/<object-storage-namespace>/<firstname.lastname>/<repo-name>`
+ If the variable is not set or is an empty string, the push will fail (but the docker image will be built).
+
+2. Make sure to be in backend/target/classes/wallet directory then execute
+   ```
+   <copy>unzip ~/mtdrworkshop/setup-dev-environment/wallet.zip</copy>
+   ```
+
+3. Pick mtdrb_tp service alias (see the list of aliases in
+   ./backend/target/classes/wallet/tnsnames.ora)
+
+   ![](images/tnsnames-ora.png " ")
+
+4. Edit ./backend/target/classes/application.yaml to set the database service and user password
+  ![](images/application-yaml.png " ")
+
+5. Copy the edited ./backend/target/classes/application.yaml to ./backend/src/main/resources/application.yaml
+
+6. Edit ./backend/src/main/java/com/oracle/todoapp/Main.java
+    - Locate the following code fragment
+    ![](images/CORS-Main.png " ")
+    - Replace `eu-frankfurt-1` in  `"https://objectstorage.eu-frankfurt-1.oraclecloud.com"` by your region
+
+    - Save the file
+
+7. Run `build.sh` script to build and push the
+    microservices images into the repository
+
+    ```
+    <copy>cd $MTDRWORKSHOP_LOCATION/backend; ./build.sh</copy>
+    ```
+  In a couple of minutes, you should have successfully built and pushed the images into the OCIR repository.
+
+8. Check your container registry from the root compartment
+    - Go to the Console, click the hamburger menu in the top-left corner and open
+    **Developer Services > Container Registry**.
+
+   ![](images/Registry-root-compart.png " ")
+
+9. Mark Access as Public  (if Private)  
+   (**Actions** > **Change to Public**):
+
+   ![](images/Public-access.png " ")
+
+## **STEP 3**: Deploy on Kubernetes and Check the Status
+
+1. Run the `deploy.sh` script
+
+  ```
+  <copy>cd $MTDRWORKSHOP_LOCATION/backend; ./deploy.sh</copy>
+  ```
+
+--> service/todolistapp-helidon-se-service created
+--> deployment.apps/todolistapp-helidon-se-deployment created
+
+2. Check the status using the following commands
+$ kubectl get services
+
+The following command returns the Kubernetes service of MyToDo application with a load balancer exposed through an external API
+  ```
+  <copy>kubectl get services</copy>
+  ```
+
+![](images/K8-service-Ext-IP.png " ")
+
+3. $ kubectl get pods
+  ```
+  <copy>kubectl get pods</copy>
+  ```
+
+![](images/k8-pods.png " ")
+
+5. Continuously tailing the log of one of the pods
+
+  $ kubectl logs -f <pod name>
+  Example kubectl lgs -f todolistapp-helidon-se-deployment-7fd6dcb778-c9dbv
+
+  Returns:
+  http://130.61.66.27/todolist
+
+## **STEP 4**: UnDeploy (optional)
+
+  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.
+
+  1. Run the `undeploy.sh` script
+  ```
+    <copy>cd $MTDRWORKSHOP_LOCATION/backend; ./undeploy.sh</copy>
+  ```
+  2. Rebuild the image + Deploy + (Re)Configure the API Gateway
+
+
+## **STEP 5**: Configure the API Gateway
+
+The API Gateway protects any RESTful service running on Container Engine for Kubernetes, Compute, or other endpoints through policy enforcement, metrics and logging.
+Rather than exposing the Helidon service directly, we will use the API Gateway to define cross-origin resource sharing (CORS).
+
+1. From the hamburger  menu navigate **Developer Services** > **API Management > Create Gateway**
+   ![](images/API-Gateway-menu.png " ")
+
+2. Configure the basic info: name, compartment, VCN and Subnet
+    - VCN: pick on of the vitual circuit network
+    - Subnet pick the public subnet   
+    The click "Create"
+  ![](images/Basic-gateway.png " ")
+
+3. Click on Todolist gateway
+       ![](images/Gateway.png " ")
+
+4. Click on Deployments
+   ![](images/Deployment-menu.png " ")
+
+5. Create a todolist deployment
+   ![](images/Deployment.png " ")
+
+
+6. Configure Cross-origin resource sharing (CORS) policies.
+  - CORS is a security mechanism that will prevent running application loaded from origin A  from using resources from another origin B.
+  - Allowed Origins: is the list of all servers (origins) that are allowed to access the API deployment typically your Kubernetes cluster IP.
+  - Allowed methods: GET, PUT, DELETE, POST, OPTIONS are all needed.
+    ![](images/Origins-Methods.png " ")
+
+7. Configure the Headers
+    ![](images/Headers.png " ")
+
+8. Configure the routes: we will define two routes:
+    - /todolist for the first two APIs: GET, POST and OPTIONS
+    ![](images/Route-1.png " ")
+
+    - /todolist/{id} for the remaining three APIs: (GET, PUT and DELETE)
+    ![](images/Route-2.png " ")
+
+
+## **STEP 6**: Testing the backend application through the API Gateway
+
+1. Navigate to the newly create Gateway Deployment Detail an copy the endpoint
+   ![](images/Gateway-endpoint.png " ")
+
+2. Testing through the API Gateway endpoint
+  postfix the gateway endpoint with "/todolist" as shown in the image below
+   ![](images/Backend-Testing.png " ")
+
+  It should display the Todo Item(s) in the TodoItem table. At least the row you have created in Part I.
+
+Congratulations, you have completed lab 2; you may now [proceed to the next lab](#next).
+
+## Acknowledgements
+
+* **Author** -  - Kuassi Mensah, Dir. Product Management, Java Database Access
+* **Contributors** - Jean de Lavarene, Sr. Director of Development, JDBC/UCP
+* **Last Updated By/Date** - Kuassi Mensah, Database Product Management,  April 2021

mtdrworkshop/frontend/Readme.md

@@ -0,0 +1,184 @@
+# Frontend (ReactJS)
+
+## Introduction
+
+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.
+
+Estimated Lab Time: 15-minutes
+
+### Objectives
+
+In this lab, you will:
+- Clone the workshop git repository on your laptop
+- Set the API Gateway endpoint
+- Run the ReactJS frontend code in Dev Mode then Build for Production
+- Host the production build on the Oracle Cloud's object storage
+
+### Understanding the ReactJS application
+
+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.
+
+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.
+
+The App component also maintains the following states:
+
+- "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.
+
+- "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.
+
+- "error" stores the error messages received during the API calls.
+
+The index.css file contains all the styles for the application.
+
+### Prerequisites
+
+1. This lab requires the completion of lab 1 and 2
+
+2. You will be using the npm command, make sure it is installed
+
+  ```
+  <copy>npm --version</copy>
+  ```
+
+  if not please install Node for your laptop, using the following
+  link: `https://bit.ly/3evGlEo`.
+
+3. The lab requires also Go lang.
+
+  "go version" -> `go version go1.15.2 darwin/amd64`
+
+  ```
+  <copy>go version</copy>
+  ```
+If not installed, please install Go (see https://golang.org/doc/)
+
+## **STEP 1**: Configure API.js
+
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+
+1. clone again the git repository to a directory on your laptop (we only need the front end in this lab)
+  ```
+  <copy>git clone https://github.com/oracle/oci-react-samples/mtdrworkshop.git</copy>
+  ```
+
+2. cd frontend
+
+3. Run the following npm commands to install the required packages
+
+  ```
+  <copy>npm install --save typescript</copy>
+  ```
+  ```
+  <copy>npm install</copy>
+  ```
+  - In case of errors, try the following command
+ ```
+ <copy>npm audit fix --force</copy>
+ ```
+  - Ideally, npm -version should return > 6.14.x AND Node version > 14.16.x
+  If npm version < 6.14.x then install the latest Node using
+   https://bit.ly/3evGlEo
+
+4. Update API_LIST in API.js
+
+  - Make sure to be in frontend/src directory
+ ```
+ <copy>cd frontend/src</copy>
+ ```
+ - In the Cloud console, navigate to **Developer Services > API Management**
+ - Click on your Gateway and go to Deployment
+ - Copy the Endpoint
+ - Paste the endpoint as the value of API_LIST and append "/todolist"
+
+  Example  
+  const API_LIST = 'https://xxxxxxxxxx.apigateway.eu-frankfurt-1.oci.customer-oci.com/todolist';
+
+  - Save the modified API.js file
+
+## **STEP 2**: Run in Dev Mode then Build for Production
+
+1. In the project directory, run the app in the development mode <br />
+
+  ```
+  <copy>npm start</copy>
+  ```
+
+2. Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+
+3. The page will reload if you make edits.<br />
+   You will also see any lint errors in the console.
+
+4. Cancel the developer mode execution and build the app for production to the `build` folder.<br />
+
+- Issue "Ctrl-c" to cancel the developer mode executions
+
+- Execute npm run build
+  ```
+  <copy>npm run build</copy>
+  ```
+It correctly bundles React in production mode (into the build folder) and optimizes the build for the best performance.
+
+  ![](images/Run-build.png " ")
+
+The build is minified and the filenames include the hashes.<br />
+Your app is ready to be deployed!
+
+See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+
+## **STEP 3**: Hosting on the Oracle Cloud's object storage
+
+1. Open up the hamburger menu in the top-left corner of the Console and select
+**Object Storage > Object Storage**.
+
+    - Create the 'mtdrworkshop' bucket
+
+2. Install the Staci utility for copying directories to OCI object storage
+   bucket with folder hierarchies
+
+  - git clone https://github.com/maxjahn/staci.git
+
+  ```
+  <copy>git clone https://github.com/maxjahn/staci.git</copy>
+  ```
+
+  - cd staci
+
+  ```
+  <copy>cd staci</copy>
+  ```
+
+  - go get -d
+
+  ```
+  <copy>go get -d</copy>
+  ```
+
+  - go build
+
+  ```
+  <copy>go build</copy>
+  ```
+
+3. Upload a static build into the bucket, using the staci binary
+
+```
+<copy>./staci/staci -source build -target mtdrworkshop</copy>
+```
+
+- The application is visible in the 'mtdrworkshop' bucket of your tenancy
+
+- Click on the index.html object and copy the URL of the index object
+
+  ![](images/bucket-index.png " ")
+
+- You may now run the application from Object store, using the URL of the index that you've copied above.
+
+  ![](images/MyToDo.png " ")
+
+Congratulations for completing the entire lab!!
+
+## Acknowledgements
+
+* **Author** -  - Kuassi Mensah, Dir. Product Management, Java Database Access
+* **Contributors** - Jean de Lavarene, Sr. Director of Development, JDBC/UCP
+* **Last Updated By/Date** - Kuassi Mensah, Database Product Management,  April 2021