Merge remote-tracking branch 'upstream/main'

23aifree/adb-free-container-setup/inst-auth-container-setup.md

@@ -21,109 +21,129 @@ This lab assumes you have:
 
 In the LiveLabs Sandbox, we will download the image from an OCI bucket. However, when using your own environment you will download the image directly from the Oracle Container Registry. That process is detailed in the free tier instructions.
 
-**_Note:_** _All of the following commands are to be run in the remote desktop's terminal._
+**_Reminder:_** _All of the following commands are to be run in the remote desktop's terminal._
 
-1.  **Set the OCI CLI environment variables.** Our image is stored in the Toronto region and we're using the instance principal authorization method. Run the following commands in the terminal to configure the OCI CLI accordingly.
+1. **Download the container image and workshop resources.** The following commands download all of the resources we'll use in the workshop. The most important file is the YAML file, which provides the configuration details of the container. We'll take a closer look at how this file works shortly.
 
     ```
     <copy>
-    export OCI_CLI_REGION=ca-toronto-1
-    export OCI_CLI_AUTH=instance_principal
-    </copy>
-    ```
-     ![OCI_CLI_AUTH](images/aivs_lab1_task1_step1.png)
-2. **Download the image from Object Storage.** 
+    ## Downloading the container image.
+    oci os object get -bn image_bucket -ns c4u04 --name adb-free-23ai.tar.gz --file adb-free-23ai.tar.gz
 
-    ```
-    <copy>
-    oci os object get -bn image_bucket -ns c4u04 --name adb-free-23ai.tar.gz --file /tmp/adb-free-23ai.tar.gz
+    ## Downloading both the container and workshop resources. 
+    wget https://objectstorage.ca-toronto-1.oraclecloud.com/p/GDCjmPfuRMx-juvDGT0Mn7ZsaI_O5y_PsGg41xcLVVl8vewGOm6Ns4zeLsTPAr3p/n/c4u04/b/apex-images/o/configuration-files.zip -P /tmp
+
+    # Opening the zip file.
+    unzip -q /tmp/installation-files.zip
     </copy>
     ```
-    ![IMAGE_DOWNLOAD](images/aivs_lab1_task1_step2.png)
+    ![Download container image](images/download-image.png)
 
-3. **Download the container installation files.** We'll be using three files to launch and configure the container. Read their descriptions below and proceed to downloading them with provided command.
 
-    **podman-compose.yaml -** The YAML file provides the configuration details of the container. These details prepare the container to deploy ADB 23ai Free.<br />
-    **db-config.sh + reset-image-prefix.sql -** Together, these scripts redirect APEX to images behind our firewall rather than their default location. This allows APEX to run properly on LiveLabs without any compliance breaches. 
+2. **Load the image into the podman catalog. (~5 mins)** Podman-load copies the image from the local docker archive into the podman container storage. This will take about 5 minutes--let's review the YAML file in the meantime.
 
     ```
     <copy>
-    wget https://objectstorage.ca-toronto-1.oraclecloud.com/p/HjeUhzJMB3rlrIy076kDM69y3eTh788gv1GmjIK5pknxl22Di9HnNai3k7LsskFX/n/c4u04/b/apex-images/o/compose.zip -P /tmp
-    unzip -q /tmp/compose.zip
+    podman load -i adb-free-23ai.tar.gz
     </copy>
     ```
-    ![WGET_COMMAND](images/aivs_lab1_task1_step3.png)
-
-4. **Download the container resource files.** The following command downloads the vector embedding model and the sample schema (for the vector search labs) and copies it into the container. Refer to Appendix 1: Understanding the YAML File for more details.
+    ![Load image into podman catalog](images/podman-load-image.png)
 
+3. **Review the YAML file.** Run the following command to learn more about how the YAML file helps launch the container image.
     ```
     <copy>
-    wget https://objectstorage.ca-toronto-1.oraclecloud.com/p/ECpUzU1rO90NPtySY1_evufBPmmOZAOFriZgPpmHo4mZy2ARpZmZ_lVtfVmY3zD3/n/c4u04/b/apex-images/o/container-files.zip -P /tmp
-    unzip -q /tmp/container-files.zip
+    cat podman-compose.yml
     </copy>
     ```
-    ![WGET_COMMAND](images/aivs_lab1_task1_step4.png)
-5. **Load the image into the podman catalog. (~5 mins)** Our image has been downloaded locally. Podman-load copies the image from the local docker archive into the podman container storage. 
 
     ```
-    <copy>
-    podman load -i /tmp/adb-free-23ai.tar.gz
-    </copy>
+    version: "3.9"
+    services:
+        adb-free:  # Name of the service/container.
+            image: container-registry.oracle.com/database/adb-free:latest-23ai # The container image to use. In this case, it's an Oracle Autonomous Database Free image.
+
+    environment:  # Environment variables passed to the container.
+      - WORKLOAD_TYPE=ATP  # Specify the workload type (ATP stands for Autonomous Transaction Processing).
+      - WALLET_PASSWORD=Welcome_12345  # Password for the database wallet.
+      - ADMIN_PASSWORD=Welcome_12345  # Admin user password for the database.
+
+    ports:  # Mapping of host ports to container ports.
+      - "1521:1522"  # Map host port 1521 to container port 1522 (database listener port).
+      - "1522:1522"  # Map host port 1522 to container port 1522 (alternative database listener port).
+      - "8443:8443"  # Map host port 8443 to container port 8443 (HTTPS port).
+      - "27017:27017"  # Map host port 27017 to container port 27017 (MongoDB port).
+
+    volumes:  # Mount host directories/files into the container.
+      - "/home/oracle/mount-files/:/u01/mount-files:Z"
+
+    devices:  # Allow the container to access specific devices on the host.
+      - /dev/fuse  # /dev/fuse is required for file system operations like mounting.
+
+    cap_add:  # Add Linux capabilities to the container.
+      - SYS_ADMIN  # SYS_ADMIN capability is required for mounting file systems.
+
+    restart: on-failure  # Automatically restart the container if it exits with a non-zero status.
+
+    userns_mode: "keep-id"  # Keep the user namespace mapping, meaning the container runs with the same user ID as on the host.
     ```
-    ![PODMAN_IMAGE_LOAD](images/aivs_lab1_task1_step5.png)
 
-6. **Launch the image.** The podman-compose command will configure and run the container image based on your YAML file. You can configure the ADB to be suited for any workload type. However, we've preset the workload type to ATP.
+4. **Launch the image.** The podman-compose command will configure and run the container image based on your YAML file. The terminal will output "exit code: 0" when the container successfully launches.
 
     ```
-    <copy>
-    podman-compose up
+    <copy>  
+    podman-compose up -d
     </copy>
     ```
-    ![WGET_COMMAND](images/aivs_lab1_task1_step6.png)
-7. **Confirm the container is up and running in a new terminal tab.** In another tab of the terminal, run this command. 
+    ![Stand up container image](images/podman-compose-up.png)
+
+5. **Confirm the container is up and running.** This command generates the name and current status for all of your running containers.
 
       ```
     <copy>
-    podman ps
+    podman ps --format "{{.Names}} {{.Status}}"
     </copy>
     ```
-    ![PODMAN_PS](images/aivs_lab1_task1_step7.png)
+    ![Check container status](images/check-container-status)
 
-9. **Confirm the files were pre-loaded into the container.**
+6. **Confirm the files were pre-loaded into the container.**
     ```
     <copy>
-    podman exec -it oracle_adb-free_1 ls /u01
-    podman exec -it oracle_adb-free_1 ls /u01/scripts
-    podman exec -it oracle_adb-free_1 ls /u01/customer-orders
+    podman exec -it oracle_adb-free_1 ls /u01/mount-files
     </copy>
     ```
     ![PODMAN_CONFIRM_PRELOADS](images/aivs_lab1_task1_step8.png)
-10. **Relocate tnsnames.ora in the container.** 'tnsnames.ora' is a configuration file, storing the database details necessary for connection. We're moving the file into a directory that's meant for our database for easy connection.
+   
+7. **Relocate tnsnames.ora in the container.** 'tnsnames.ora' is a configuration file, storing the database details necessary for connection. We're moving the file into a directory that's meant for our database for easy connection.
     ```
     <copy>
     podman exec -it oracle_adb-free_1 cp /u01/app/oracle/wallets/tls_wallet/tnsnames.ora /u01/app/oracle/product/23.0.0.0/dbhome_1/network/admin/tnsnames.ora
     </copy>
     ```
     ![PODMAN_EXEC](images/aivs_lab1_task1_step9.png)
 
+8. **Confirm ORDS is running.**
+    ```
+    <copy>
+    podman exec -it oracle_adb-free_1 jps -l | grep ords
+    </copy>
+    ```
 
-
-## Task 2: Access APEX & SQL Developer Web
-
-Oracle Autonomous Database Free has APEX and ORDS (a.k.a Database Actions) preinstalled. Let's see how you can get started!
-
-1. **Re-configure the APEX image.** We'll first need to redirect APEX to use the images behind our firewall. Run this command in the terminal to do so.
+9. **Configure the APEX image.** We'll first need to redirect APEX to use the images behind our firewall. Run this command in the terminal to do so. This is only required for APEX use in Livelabs.
 
     ```
     <copy>
     podman exec -it oracle_adb-free_1 /bin/sh -c "/u01/scripts/db-config.sh"
     </copy>
     ```  
 
-2. **Open Google Chrome.** Click Activities >> Google Chrome icon, to open a new Chrome window.
-    ![ACTIVITY_WINDOW](images/aivs_lab1_task2_step2.png)
+## Task 2: Access APEX & SQL Developer Web
+
+Oracle Autonomous Database Free has APEX and ORDS (a.k.a Database Actions) preinstalled. Let's see how you can get started!
+
+1. **Open Google Chrome.** Click Activities >> Google Chrome icon, to open a new Chrome window.
+    [Insert gif]
     
-3. **Launch ORDS.** Paste the following URL into your Chrome browser to Launch ORDS.
+2. **Launch ORDS.** Paste the following URL into your Chrome browser to Launch ORDS.
 
     ```
     <copy>
@@ -132,44 +152,28 @@ Oracle Autonomous Database Free has APEX and ORDS (a.k.a Database Actions) prein
     ```
     ![ORDS landing page](images/ords-landing.png)
 
-4. **Sign into ORDS.** 
+3. **Sign into ORDS.** <br/> <br/>
     
-    **Username -** admin
+    **Username -** admin<br/>
     **Password -** Welcome_12345 (or the custom password you specified in Task 1, Step 5.)
 
     ![Sign into DB Actions](images/sign-in-ords.png)
 
+4. **Launch SQL Developer Web.** You now have access to Database Actions! This is where you'll find both APEX and SQL Developer Web. For now, we'll only launch SQL Developer Web.
 
-5. **Launch APEX.** You now have access to Database Actions! Let's first click APEX to test it out.
-Click "Go to Oracle APEX".
-
-    ![PODMAN_PS](images/aivs_lab1_task2_step7.png)
-
-6. **Sign-in to APEX.** 
+    ![PODMAN_PS](images/aivs_lab1_task2_step5.png)
 
-    **Username -** admin
+5. **Sign-in to SQL Developer Web.** <br/>
+    **Username -** admin <br/>
     **Password -** Welcome_12345 (or the custom password you specified in Task 1, Step 5.)
 
-    ![Sign into APEX](images/sign-in-apex.png)
-
-
-7. **Launch SQL Developer Web.** Let's go back to the landing page and view SQL Developer Web.
-
-    ```
-    <copy>
-    https://localhost:8443/ords
-    </copy>
-    ```
-    ![PODMAN_PS](images/aivs_lab1_task2_step5.png)
-
-8. **Sign-in to SQL Developer Web.** 
+    ![Sign into DB Actions](images/sign-in-ords.png)
 
-    **Username -** admin
-    **Password -** Welcome_12345 (or the custom password you specified in Task 1, Step 5.)
+6. **Lauch the SQL worksheet.** Select the 'SQL' tab, as shown below.
+    ![Launch the SQL Tab](images/sql-worksheet.png)
 
-9. **Lauch the SQL worksheet.** Select the 'SQL' tab, as shown below.
 
-You may proceed to the next lab.
+**You may proceed to the next lab.**
 
 
 ## Appendix 1: Restart Docker Container

23aifree/introduction/intro-aivs-adb.md

@@ -4,7 +4,7 @@
 
 With Oracle Autonomous Database Free, you get to explore the newest features of Oracle Database 23ai at no-cost! This workshop guides you through the container image installation to get started in your own environment, without requiring access to Oracle Cloud Infrastructure Console or to the internet.
 
-After installation, you'll learn how to further extend the capabilities of the Autonomous Database by installing ORDS, APEX, and SQLcl. Once your environment is set for development, you'll (introduce the vector search activity) and see just how easy it is to leverage AI Vector Search. 
+After installation, you'll learn how to further extend the capabilities of the Autonomous Database by accessing APEX, and SQL Developer Web. Once your environment is set for development, you'll (introduce the vector search activity) and see just how easy it is to leverage AI Vector Search. 
 
 ### **About the Oracle Autonomous Database 23ai Free Container Image**
 Oracle Autonomous Database provides an easy-to-use, fully autonomous database that scales elastically and delivers fast query performance. As a service, Autonomous Database does not require database administration. Autonomous Database provides a fully managed Oracle Database that is available on Oracle Cloud Infrastructure.
@@ -33,7 +33,6 @@ In this workshop, you will:
 * Learn the Oracle AI Vector Search process on ADB.
 
 
-
 ###**Prerequisites**
 
 In order to do this workshop you need
@@ -52,6 +51,6 @@ or
 
 
 ## Acknowledgements
-* **Authors** - Brianna Ambler, Dan Williams Database Product Management
+* **Authors** - Brianna Ambler, Database Product Management
 * **Contributors** - Brianna Ambler, Dan Williams, Database Product Management
-* **Last Updated By/Date** - Dan Williams, Database Product Management, July 2024
+* **Last Updated By/Date** - Brianna Ambler, Database Product Management, August 2024

23aifree/introduction/using-novnc-remote-desktop.md

@@ -0,0 +1,134 @@
+# Use noVNC remote desktop
+
+## Introduction
+This lab will show you how to get started with your workshop with a remote desktop session.
+
+Estimated Time: 5 minutes
+
+### Objectives
+In this lab, you will:
+- Enable fullscreen display of remote desktop session
+- Enable remote clipboard integration
+- Open the workshop guide from the remote desktop
+
+### Prerequisites
+
+This lab assumes you have:
+- Provisioned VM Instance configured with noVNC
+
+## Task 1: Launch noVNC from LiveLabs
+
+1. In your reservation tab, select "View Login Info".
+
+    ![View login info.](./images/view-login-info.png)
+
+2. Select "Launch Remote Desktop".
+
+    ![View login info.](./images/launch-remote-desktop.png)
+
+## Task 2: Enable Full-screen Display
+For seamless desktop integration and to make the best use of your display, perform the following tasks to render your remote desktop session in fullscreen mode.
+
+1. Click on the small gray tab on the middle-left side of your screen to open the control bar.
+
+    ![Open control bar](./images/novnc-fullscreen-1.png " ")
+
+2. Select *Fullscreen* to render the session on your entire screen.
+
+    ![Click full screen](./images/novnc-fullscreen-2.png " ")
+    ![Open full screen](./images/novnc-fullscreen-3.png " ")
+
+## Task 3: Enable Copy/Paste from Local to Remote Desktop
+During the execution of your labs, you may need to copy text from your *local PC/Mac* to the *remote desktop*, such as commands from the lab guide. While such direct copy/paste isn't supported as you will realize, you may proceed as indicated below to enable an alternative *local-to-remote clipboard* with Input Text Field.
+
+1. Continuing from the last task above, Select the *clipboard* icon
+
+    ![Click clipboard](./images/novnc-clipboard-1.png " ")
+
+2. Copy some text from your local computer as illustrated below and paste it into the clipboard widget, then finally open up the desired application (e.g. Terminal) and paste accordingly using *mouse controls*
+
+    ![Copy text](./images/novnc-clipboard-2.png " ")
+
+    >**Note:** Please make sure you initialize your clipboard with Step 1 shown in the screenshot above before opening the target application in which you intend to paste the text. Otherwise will find the *paste* function in the context menu grayed out when attempting to paste for the first time.
+
+## Task 4: Open Your Workshop Guide
+
+1. If the *Web* browser window(s) is(are) not already open side-by-side, double-click the *Get Started with your Workshop* icon from the remote desktop. This will launch one or two windows depending on the workshop.
+
+    ![Get Started with your Workshop](./images/novnc-launch-get-started-1.png " ")
+
+2. On the left window is your workshop guide and depending on your workshop, you may also have one or two browser tabs loaded with web apps. e.g. Weblogic console, Enterprise Manager Cloud Console, or a relevant application to your workshop such as SQL Developer, JDeveloper, etc.
+
+    ![Workshop guide and sample webapp](./images/novnc-launch-get-started-2.png " ")
+    ![Workshop guide and Oracle SQL Developer](./images/novnc-launch-get-started-3.png " ")
+
+## (Optional) Task 5: Open the Terminal
+
+    If you need the terminal and it's not already up, open it as shown below._
+    ![Open terminal](images/open-terminal.gif)
+
+You may now **proceed to the next lab**.
+
+## Appendix: Connect Remotely Using SSH
+
+While your workshop can be executed end-to-end from the remote desktop, follow the steps provided below if you need to access the instance remotely using an SSH client such as Putty, Unix/Linux/MacOS Terminal, OCI cloud shell, and other terminal emulators available on Windows.
+
+>**Note:** In this section you are enabling SSH access to the OS user running the remote desktop. This could be oracle, opc, or any other OS user for which the noVNC remote desktop has been configured.
+
+This assumes that you already have an RSA-type SSH key-pair available on the local system where you will be connecting from. If you don't and for more info on creating and using SSH keys for your specific platform and client, please refer to the guide [Generate SSH Keys](https://oracle-livelabs.github.io/common/labs/generate-ssh-key)
+
+1. Open the remote clipboard on the remote desktop as shown in *Task 2* and launch a terminal session
+
+2. Paste the block below onto the remote clipboard first, then onto the terminal to create or update the file *$HOME/.ssh/authorized_keys* with the *Vi* editor
+
+    ```text
+    <copy>
+    cd $HOME; mkdir .ssh; cd .ssh
+    vi authorized_keys
+    </copy>
+    ```
+
+    ![Update authorized keys](./images/novnc-copy-pub-key-4.png " ")
+
+3. From the local system (e.g. your laptop) and with the exception of *Putty* users, locate the SSH public key from the key-pair, open it, and copy the entire content to the clipboard.
+
+    ![Copy SSH public key](./images/novnc-copy-pub-key-1.png " ")
+
+    If using Putty you must load the private key (*.ppk*) into the *Puttygen* utility to see the relevant public key block to copy. Do not copy the content of the public key file directly as it will not work.
+
+    ![Copy SSH public key using Putty](./images/novnc-copy-pub-key-2.png " ")
+
+4. Paste the copied public key onto the remote clipboard first, then onto the terminal where you opened *authorized_keys* for edit
+
+    ![Paste SSH key to authorized keys in remote desktop](./images/novnc-copy-pub-key-3.png " ")
+
+5. Save and exit the *Vi* editor
+
+6. Set required permissions on *$HOME/.ssh* and *authorized_keys*
+
+    ```
+    <copy>
+    chmod 0700 $HOME/.ssh
+    chmod 0600 $HOME/.ssh/authorized_keys
+    </copy>
+    ```
+
+7. Test/Validate connectivity using the private key (for Unix/Linux/MacOS Terminal, OCI cloud shell, and Terminal emulators on Windows such as Cygwin and MobaXterm).
+
+    ```text
+    ssh -i [path to private key] remote-user@[instance-public-ip-address]
+    ```
+
+    e.g.
+    ```text
+    <copy>
+    ssh -i /home/appuser1/.ssh/livelabs_rsa_priv [email protected]
+    </copy>
+    ```
+
+    For Putty, please refer to the guide [Generate SSH Keys](https://oracle-livelabs.github.io/common/labs/generate-ssh-key) on how to establish the connection using the *.ppk* private key.
+
+## Acknowledgements
+* **Author** - Rene Fontcha, LiveLabs Platform Lead, NA Technology
+* **Contributors** - Arabella Yao, Product Manager, Database Product Management
+* **Last Updated By/Date** - Ramona Magadan, March 2024