diff --git a/gdk-oci-mysql/00-introduction/introduction.md b/gdk-oci-mysql/00-introduction/introduction.md new file mode 100644 index 000000000..e19c35800 --- /dev/null +++ b/gdk-oci-mysql/00-introduction/introduction.md @@ -0,0 +1,62 @@ +# Introduction + +## About this Workshop + +This workshop takes you step by step through the process of building a Java application with the Graal Development Kit for Micronaut (GDK), Oracle Cloud Infrastructure (OCI) MySQL HeatWave Database service and Secrets in OCI Vault. +You'll use GraalVM Native Image to package and run the application as a native executable. + +It is aimed at application developers and DevOps engineers with an intermediate knowledge of Java. + +Estimated Workshop Time: 75 minutes + +### What is Graal Development Kit for Micronaut? + +The [Graal Development Kit for Micronaut (GDK)](https://graal.cloud/gdk) is an Oracle build of the open source Micronaut® framework. The GDK provides a curated set of Micronaut framework modules that simplify cloud application development, are designed for ahead-of-time compilation with GraalVM Native Image, and are fully supported by Oracle. The GDK also provides project creation utilities, VS Code and IntelliJ extensions to simplify application development and deployment. + +### What is Micronaut? + +The [Micronaut® framework](https://micronaut.io/) is a modern, JVM-based framework to build modular, easily testable microservice and serverless applications. By avoiding runtime reflection in favor of annotation processing, Micronaut improves the Java-based development experience by detecting errors at compile time instead of runtime, and improves Java-based application startup time and memory footprint. Micronaut includes a persistence framework called Micronaut Data that precomputes your SQL queries at compilation time making it a great fit for working with databases like MySQL, Oracle Autonomous Database, etc. + +> Micronaut® is a registered trademark of Object Computing, Inc. Use is for referential purposes and does not imply any endorsement or affiliation with any third-party product. + +### What is GraalVM Native Image? + +[GraalVM Native Image](https://www.graalvm.org/) technology compiles Java applications ahead-of-time into self-contained native executables that are small in size, start almost instantaneously, provide peak performance with no warmup, and require less memory and CPU. Only the code that is required at run time by the application gets added into the executable file. Native Image is perfect for containerized workloads and microservices — which is why it has been embraced by Micronaut, Spring Boot, Helidon, and Quarkus. + +The GDK modules are designed for ahead-of-time compilation with GraalVM Native Image to produce native executables that are ideal for microservices: they have a small memory footprint, start instantly, and provide peak performance with no warmup. + +> Graal Development Kit for Micronaut, and Oracle GraalVM are available at no additional cost on Oracle Cloud Infrastructure (OCI). + +### Objectives + +In this workshop, you will: + +* Create a new OCI MySQL HeatWave Database instance and a Vault +* Use Visual Studio Code (VS Code) from a remote desktop running in an OCI Compute Instance +* Review the application source code developed with the Graal Development Kit for Micronaut +* Build and run the application against a local MySQL database in a container +* Build and run a native executable and connect to the local MySQL database +* Configure the MySQL HeatWave Database instance and the Vault +* Configure the application to use the MySQL HeatWave Database instance and the Vault +* Build a native executable for the application using GraalVM Native Image and connect to the MySQL HeatWave Database instance + +### Prerequisites + +This workshop assumes you have: + +* Some familiarity with Oracle Cloud Infrastructure (OCI) +* Understanding of the Java programming language +* Oracle GraalVM for JDK 17 +* Visual Studio Code (VS Code) +* A browser with access to the internet +* An Oracle Cloud Infrastructure (OCI) account with adequate permissions + +## Learn More + +* [Graal Development Kit for Micronaut](https://graal.cloud/gdk/) + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/01-prepare-setup/prepare-setup.md b/gdk-oci-mysql/01-prepare-setup/prepare-setup.md new file mode 100644 index 000000000..117d82390 --- /dev/null +++ b/gdk-oci-mysql/01-prepare-setup/prepare-setup.md @@ -0,0 +1,85 @@ +# Prepare Setup + +## Introduction + +This lab will show you how to download the Oracle Resource Manager (ORM) stack zip file needed to set up the resources needed to run this workshop. + +*Estimated Lab Time:* 5 minutes + +### Objectives + +* Download ORM stack +* (*Optional*) Configure an existing Virtual Cloud Network (VCN) +* Select a Compartment for the workshop + +### Prerequisites + +This lab assumes you have: + +* An Oracle Cloud account + +## Task 1: Download Oracle Resource Manager (ORM) stack zip file + +1. Click on the link below to download the Resource Manager zip file you need to build your environment: + + * [gdk-oci-mysql-ll-orm.zip](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/oci-library/gdk-oci-mysql-ll-orm.zip) + +2. Save it in your downloads folder. + +3. (*Recommended*) We strongly recommend using this stack to create a new self-contained/dedicated VCN along with your instance. Skip to **Task 3** to follow the recommendation. + +4. Alternatively, if you would rather use an existing VCN then proceed to the next task to update your existing VCN with the required network security rules. + +## Task 2: Add Network Security Rules to an Existing VCN + +This workshop requires a certain number of ports to be available, a requirement that is automatically met by using the default ORM stack execution that creates a new dedicated VCN. + +However, if you would rather use an existing VCN/subnet, follow these steps to add the following rules to the network security list. + +1. From the Oracle Cloud Console navigation menu, go to **Networking >> Virtual Cloud Networks**. +2. Choose your network. +3. Under **Resources**, select **Security Lists**. +4. Click on **Default Security Lists** under the **Create Security List** button. +5. Click **Add Ingress Rules** button. +6. Create a rule for each row in the *Ingress* table below: + + | Stateless | Source Type | Source CIDR | IP Protocol | Source Port Range | Destination Port Range | Description | + | :------------- | :---------: | :---------: | :---------: | :---------------: | :--------------------: | :------------------------- | + | No (unchecked) | CIDR | 0.0.0.0/0 | TCP | All | 80 | Remote Desktop using noVNC | + | No (unchecked) | CIDR | 0.0.0.0/0 | TCP | All | 6080 | Remote Desktop using noVNC | + {: title="Network Ingress Security Rules"} + +7. Select **Egress Rule** from the left panel. +8. Click **Add Egress Rule** button +9. Create a rule for each row in the *Egress* table below: + + | Stateless | Source Type | Destination CIDR | IP Protocol | Source Port Range | Destination Port Range | Description | + | :------------- | :---------: | :--------------: | :---------: | :---------------: | :--------------------: | :-------------------- | + | No (unchecked) | CIDR | 0.0.0.0/0 | TCP | All | 80 | Outbound HTTP access | + | No (unchecked) | CIDR | 0.0.0.0/0 | TCP | All | 443 | Outbound HTTPS access | + {: title="Network Egress Security Rules"} + +## Task 3: Select a Compartment for the Workshop + +We recommend you use a single compartment for the workshop. We will refer to this as your workshop compartment. This is the compartment where you will provision all the resources - Oracle Resource Manager (ORM) Stack, Compute Instance, VCN/Subnet, Instance Principals, Policies, MySQL HeatWave Database, Vault - needed for the workshop. + +1. From the Oracle Cloud Console navigation menu, go to **Identity & Security >> Identity >> Compartments**. +2. Go to your workshop compartment. +3. Make a note of the compartment name and OCID. You will need this information in subsequent labs. + +## Task 4: Setup Compute + +Using the details from the above Tasks, proceed to the **Environment Setup** lab to set up your workshop environment using Oracle Resource Manager (ORM) with one of the following options: + +* (*Recommended*) Create Stack: **Compute + Networking** +* Create Stack: **Compute only** with an existing VCN where security lists have been updated as per **Task 2** above + +The ORM stack will provision a compute instance with 4 OCPUs, 64 GB RAM and a Remote Desktop environment. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/02-git-clone/git-clone.md b/gdk-oci-mysql/02-git-clone/git-clone.md new file mode 100644 index 000000000..d16fb184b --- /dev/null +++ b/gdk-oci-mysql/02-git-clone/git-clone.md @@ -0,0 +1,54 @@ +# Clone the Sample Application Source Code + +## Introduction + +This lab describes the steps to download the sample application source code used in the workshop. + +Estimated Lab Time: 5 minutes + +### Objectives + +In this lab, you will: + +* Clone the sample application source code + +## Task 1: Clone the Sample Application Source Code + +1. From the **Activities** menu, start a new **Terminal** window. + +2. Clone the sample application source code. + + ``` bash + + git init lab + cd lab + git remote add origin https://github.com/oracle-samples/gdk-micronaut-samples.git + git config core.sparsecheckout true + echo "gdk-oci-mysql-mvn/*">>.git/info/sparse-checkout + git pull --depth=1 origin main + + ``` + +3. Open the sample application source code from the _gdk-oci-mysql-mvn_ directory in **Visual Studio Code**. + + ``` bash + + code gdk-oci-mysql-mvn + + ``` + +4. VS Code may show a dialog box with the message "Do you trust the authors of the files in this folder?". Select **Trust the authors of all files in the parent folder 'oracle'** and click **Yes, I trust the authors**. + +5. VS Code may ask you to choose a password for new keyring. Press **Cancel** twice to close the prompt. + +6. VS Code may show a dialog box with the message "A git repository was found in the parent folders of the workspace or the open file(s). Would you like to open the repository?". Click **Never**. + + ![VS Code Question Icon](images/vs-code-question-icon.jpg#input) + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/02-git-clone/images/vs-code-question-icon.jpg b/gdk-oci-mysql/02-git-clone/images/vs-code-question-icon.jpg new file mode 100644 index 000000000..0e7299ab5 Binary files /dev/null and b/gdk-oci-mysql/02-git-clone/images/vs-code-question-icon.jpg differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/create-db-system.jpg b/gdk-oci-mysql/03-provision-mysql-db/images/create-db-system.jpg new file mode 100644 index 000000000..e9bc615b7 Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/create-db-system.jpg differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/heatwave-mysql-landing-page.jpg b/gdk-oci-mysql/03-provision-mysql-db/images/heatwave-mysql-landing-page.jpg new file mode 100644 index 000000000..9795a47ec Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/heatwave-mysql-landing-page.jpg differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/mysql-admin-user.jpg b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-admin-user.jpg new file mode 100644 index 000000000..5138205c0 Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-admin-user.jpg differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/mysql-backup-create.png b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-backup-create.png new file mode 100644 index 000000000..e4670a114 Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-backup-create.png differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/mysql-configure-hw.jpg b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-configure-hw.jpg new file mode 100644 index 000000000..d2c55d1a0 Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-configure-hw.jpg differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/mysql-db-system-form.png b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-db-system-form.png new file mode 100644 index 000000000..720a42982 Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-db-system-form.png differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/mysql-network-placement.png b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-network-placement.png new file mode 100644 index 000000000..c811ccbff Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-network-placement.png differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/images/mysql-standalone-ha.jpg b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-standalone-ha.jpg new file mode 100644 index 000000000..204e301da Binary files /dev/null and b/gdk-oci-mysql/03-provision-mysql-db/images/mysql-standalone-ha.jpg differ diff --git a/gdk-oci-mysql/03-provision-mysql-db/provision-mysql-db.md b/gdk-oci-mysql/03-provision-mysql-db/provision-mysql-db.md new file mode 100644 index 000000000..47d0af4ab --- /dev/null +++ b/gdk-oci-mysql/03-provision-mysql-db/provision-mysql-db.md @@ -0,0 +1,63 @@ +# Provision an OCI MySQL HeatWave Database + +## Introduction + +This lab describes the steps to create a new OCI MySQL HeatWave Database instance. + +Estimated Lab Time: 10 minutes + +### Objectives + +In this lab, you will: + +* Create MySQL HeatWave Database instance + +## Task 1: Create MySQL HeatWave Database instance + +1. From the Oracle Cloud Console, open the navigation menu, click **Databases**. Under **HeatWave MySQL**, click **DB Systems** + + ![Oracle Databases menu](https://oracle-livelabs.github.io/common/images/console/database-mysql.png) + +2. Select your workshop compartment from the **Compartment** drop down list on the left + + ![HeatWave MySQL Landing Page](images/heatwave-mysql-landing-page.jpg#input) + +3. Click **Create DB System**. + + ![Create DB System Button](images/create-db-system.jpg#input) + +4. You will see the **Create DB System** screen. Select **Development or testing**. + + ![Create DB System Screen](images/mysql-db-system-form.png#input) + +5. Under the **Create administrator credentials** section, enter the username as "mysqladmin" and a password of your choice. + + ![Create MySQL Admin User](images/mysql-admin-user.jpg#input) + +6. Ensure **Standalone** is selected. + + ![MySQL Standalone or HA](images/mysql-standalone-ha.jpg#input) + +7. Leave the default values in the **Network** and **Placement** sections unchanged. + + ![MySQL Network and Placement](images/mysql-network-placement.png#input) + +8. Under the **Configure hardware** section, deselect **Enable HeatWave cluster**. Leave the other default values unchanged. + + ![MySQL Configure Hardware](images/mysql-configure-hw.jpg#input) + +9. Under the **Configure backup plan** section, deselect **Enable automatic backups**. Click **Create**. + + ![Disable MySQL Automatic Backup and Create](images/mysql-backup-create.png) + + It takes about 10 minutes to provision an OCI MySQL DB System instance. Meanwhile, proceed to the next step. + +Congratulations! In this lab, you created a new OCI MySQL HeatWave Database instance in your workshop compartment. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/04-provision-vault/images/create-key-details.png b/gdk-oci-mysql/04-provision-vault/images/create-key-details.png new file mode 100644 index 000000000..0825faf58 Binary files /dev/null and b/gdk-oci-mysql/04-provision-vault/images/create-key-details.png differ diff --git a/gdk-oci-mysql/04-provision-vault/images/create-vault-button.png b/gdk-oci-mysql/04-provision-vault/images/create-vault-button.png new file mode 100644 index 000000000..8697f9407 Binary files /dev/null and b/gdk-oci-mysql/04-provision-vault/images/create-vault-button.png differ diff --git a/gdk-oci-mysql/04-provision-vault/images/create-vault-details.png b/gdk-oci-mysql/04-provision-vault/images/create-vault-details.png new file mode 100644 index 000000000..101e9c6a7 Binary files /dev/null and b/gdk-oci-mysql/04-provision-vault/images/create-vault-details.png differ diff --git a/gdk-oci-mysql/04-provision-vault/images/select-compartment-field.png b/gdk-oci-mysql/04-provision-vault/images/select-compartment-field.png new file mode 100644 index 000000000..5d1e34f27 Binary files /dev/null and b/gdk-oci-mysql/04-provision-vault/images/select-compartment-field.png differ diff --git a/gdk-oci-mysql/04-provision-vault/images/vault-menu.png b/gdk-oci-mysql/04-provision-vault/images/vault-menu.png new file mode 100644 index 000000000..b873230b3 Binary files /dev/null and b/gdk-oci-mysql/04-provision-vault/images/vault-menu.png differ diff --git a/gdk-oci-mysql/04-provision-vault/provision-vault.md b/gdk-oci-mysql/04-provision-vault/provision-vault.md new file mode 100644 index 000000000..de3fff092 --- /dev/null +++ b/gdk-oci-mysql/04-provision-vault/provision-vault.md @@ -0,0 +1,76 @@ +# Provision an OCI Vault + +## Introduction + +This lab describes the steps to create a new OCI Vault. + +Estimated Lab Time: 10 minutes + +### Objectives + +In this lab, you will: + +* Create an OCI Vault +* Create OCI Vault Master Encryption Key + +## Task 1: Create an OCI Vault + +1. From the Oracle Cloud Console, open the navigation menu, click **Identity & Security**, and then click **Vault** under **Key Management & Secret Management**. + + ![Vault menu](https://oracle-livelabs.github.io/common/images/console/id-vault.png) + +2. Select your workshop compartment from the **Compartment** drop down list on the left. + + ![Select Compartment Button](images/select-compartment-field.png) + +3. Click **Create Vault**. + + ![Create Vault Button](images/create-vault-button.png) + +4. In the **Create Vault** dialog box, provide the following details: + + ``` + Create in Compartment: + + Name: shared-vault + + Make it a virtual private vault: NO (LEAVE THE BOX UNCHECKED) + ``` + + ![Create Vault Details](images/create-vault-details.png) + + >Note: You cannot change the vault type after the vault is created. + +5. Click **Create Vault** + +## Task 2: Create OCI Vault Master Encryption Key + +1. In the **Vault** you created, navigate to **Master Encryption Key**, click **Create Key**. + +2. Provide the following details: + + ```text + Protection Mode: Software + + Name: master-key + + Key Shape Algorithm: AES (Symmetric key for Encrypt and Decrypt) + + Key Shape Length: 256 bits + + Import External key: NO (LEAVE THE BOX UNCHECKED) + ``` + + ![Create Key Details](images/create-key-details.png) + +3. Click **Create Key**. + +Congratulations! In this lab, you created a new OCI Vault with a Master Encryption Key in your workshop compartment. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/05-review-code/review-code.md b/gdk-oci-mysql/05-review-code/review-code.md new file mode 100644 index 000000000..e505070ca --- /dev/null +++ b/gdk-oci-mysql/05-review-code/review-code.md @@ -0,0 +1,217 @@ +# Review the Sample Application Source Code + +## Introduction + +This lab reviews the sample Micronaut application code used in the workshop. The application source code and build scripts are available for review in VS Code. + +The sample `Genre` application is a part of a larger `Books` demo application. However, the main goal of this lab is to demonstrate OCI MySQL HeatWave Database connectivity using GDK. Hence, the scope of the application is limited to just a single entity called `Genre` with just two columns (an ID and a name). + +The application is a simple "RESTful" microservice that exposes CRUD-like operations as APIs to list, get, put, and delete the `Genre` entity. The entity is mapped to an MySQL HeatWave Database table using the Micronaut Data JDBC feature. + +Estimated Time: 10 minutes + +### Objectives + +In this lab, you will: + +* Review the sample application source code + +## Task 1: Review the Data Source Configuration + +The configuration file contains the datasource definition + +_oci/src/main/resources/application-oraclecloud.properties_ + +``` properties +datasources.default.db-type=mysql +datasources.default.dialect=MYSQL +datasources.default.driver-class-name=com.mysql.cj.jdbc.Driver +datasources.default.url=${DATASOURCES_DEFAULT_URL:`jdbc:mysql://localhost:3306/db`} +datasources.default.username=${JDBC_USER:sherlock} +datasources.default.password=${JDBC_PASSWORD:elementary} +``` + +The use of properties, in the form `property: ${:}`, to define the datasource +enables the configuration to be externalized. For example, if an environment variable (``) such as `DATASOURCES_DEFAULT_URL` is not defined, the Micronaut framework will use the default value (``) specified. +So if `DATASOURCES_DEFAULT_URL` is not specified, the Micronaut framework sets the value of `url` to `jdbc:mysql://localhost:3306/db`. + +## Task 2: Review the Database Migration with Flyway + +[Flyway](https://flywaydb.org/documentation/) automates schema changes, significantly simplifying schema management tasks, such as migrating, rolling back, and reproducing in multiple environments. + +The application uses [Micronaut integration with Flyway](https://micronaut-projects.github.io/micronaut-flyway/latest/guide/) to create a database schema on the fly by: + +1. Including the following dependencies: + + _oci/pom.xml_ + + ``` xml + + io.micronaut.flyway + micronaut-flyway + compile + + ``` + + ``` xml + + org.flywaydb + flyway-mysql + runtime + + ``` + +2. Enabling Flyway in the _application-oraclecloud.properties_ file for the `default` datasource: + + _oci/src/main/resources/application-oraclecloud.properties_ + + ```properties + flyway.datasources.default.enabled=true + ``` + + Flyway migration is automatically triggered before the application starts. Flyway will read migration commands in the _resources/db/migration/_ directory, run them if necessary, and verify that the configured data source is consistent with them. + +3. Creating an SQL file to create a `genre` table in the database: + + _lib/src/main/resources/db/migration/V1\_\_schema.sql_ + + ``` sql + DROP TABLE IF EXISTS genre; + + CREATE TABLE genre ( + id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(255) NOT NULL UNIQUE + ); + ``` + + During application startup, Flyway runs the commands in this SQL file and creates the schema needed for the application. + +## Task 3: Review the Domain Entity + +In this example, the domain entity is a simple `Genre` object that maps to the `genre` table. It has an auto-generated `id` and a unique `name`. + +_lib/src/main/java/com/example/domain/Genre.java_ + +``` java +@Serdeable +@MappedEntity // <1> +public class Genre { +``` + +1. `@MappedEntity` specifies that the entity is mapped to the database. If your table name differs from the entity name, pass the table name as the value. For example: `@MappedEntity(value = "TABLE_NAME")`. In the case of this application, the table name `genre` matches the entity name `Genre`. + +## Task 4: Review the Repository Access + +The repository interface `GenreRepository` defines the operations to access the database. Micronaut Data implements the interface at compilation time: + +_lib/src/main/java/com/example/repository/GenreRepository.java_ + +``` java +@JdbcRepository(dialect = MYSQL) // <1> +public interface GenreRepository extends PageableRepository { // <2> + + Genre save(@NonNull @NotBlank String name); // <3> +``` + +1. `@JdbcRepository` with a specific dialect: `MYSQL` in this example. + +2. `Genre`, the entity to treat as the root entity for the purposes of querying, is established either from the method signature or from the generic type parameter specified to the `GenericRepository` interface. The repository extends from `PageableRepository`. It inherits the hierarchy `PageableRepository` → `CrudRepository` → `GenericRepository`. + + - `PageableRepository`: A repository that supports pagination. It provides `findAll(Pageable)` and `findAll(Sort)`. + - `CrudRepository`: A repository interface for performing CRUD (Create, Read, Update, Delete). It provides methods such as `findAll()`, `save(Genre)`, `deleteById(Long)`, and `findById(Long)`. + - `GenericRepository`: A root interface that features no methods but defines the entity type and ID type as generic arguments. + +3. Micronaut validation is built on the standard framework – [JSR 380](https://jcp.org/en/jsr/detail?id=380), also known as Bean Validation 2.0. Micronaut [has built-in support for validation of beans](https://docs.micronaut.io/latest/guide/#beanValidation) that are annotated with `javax.validation` annotations. The necessary dependencies are included by default when creating a new application, so you don’t need to add anything else. + +## Task 5: Review the Controller + +The controller class `GenreController` exposes the `Genre` resource with REST APIs for the common CRUD operations. + +_lib/src/main/java/com/example/controller/GenreController.java_ + +``` java +@ExecuteOn(TaskExecutors.IO) // <1> +@Controller("/genres") // <2> +class GenreController { +``` + +1. It is critical that any blocking I/O operations (such as fetching data from a database) are offloaded to a separate thread pool that does not block the Event loop. + +2. The class is defined as a controller with the [@Controller](https://docs.micronaut.io/latest/api/io/micronaut/http/annotation/Controller.html) annotation mapped to the path `/genres`. + +``` java +private final GenreService genreService; + +GenreController(GenreService genreService) { // <3> + this.genreService = genreService; +} +``` + +3. Use constructor injection to inject a bean of type `GenreService`. + +``` java +@Get("/{id}") // <4> +public Optional show(Long id) { + return genreService.findById(id); // <5> +} +``` + +4. Maps a `GET` request to `/genres/{id}`, which attempts to show a genre. This illustrates the use of a URL path variable `id`. + +5. Returning an empty optional when the genre doesn’t exist makes the Micronaut framework respond with 404 (not found). + +``` java +@Put("/{id}/{name}") // <6> +public HttpResponse update(long id, String name) { + genreService.update(id, name); + return HttpResponse + .noContent() + .header(LOCATION, URI.create("/genres/" + id).getPath()); // <7> +} +``` + +6. Maps a `PUT` request to `/genres/{id}/{name}`, which attempts to update the corresponding genre name. This illustrates the use of URL path variables `id` and `name`. + +7. It is easy to add custom headers to the response. + +``` java +@Get("/list") // <8> +public List list(@Valid Pageable pageable) { // <9> + return genreService.list(pageable); +} +``` + +8. Maps a `GET` request to `/genres/list`, which returns a list of genres. + +9. You can bind `Pageable` as a controller method argument. (For more information, see [Pageable configuration](https://micronaut-projects.github.io/micronaut-data/latest/guide/configurationreference.html#io.micronaut.data.runtime.config.DataConfiguration.PageableConfiguration).) For example, you can configure the default page size with the configuration property `micronaut.data.pageable.default-page-size`. + +``` java +@Post // <10> +public HttpResponse save(@Body("name") @NotBlank String name) { + Genre genre = genreService.save(name); + + return HttpResponse + .created(genre) + .headers(headers -> headers.location(URI.create("/genres/" + genre.getId()))); +} +``` + +10. Maps a `POST` request to `/genres`, which attempts to save a genre. + +``` java +@Delete("/{id}") // <11> +@Status(NO_CONTENT) +public void delete(Long id) { + genreService.delete(id); +} +``` + +11. Maps a `DELETE` request to `/genres/{id}`, which attempts to remove a genre. This illustrates the use of a URL path variable `id`. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/06-build-run-app-local/build-run-app-local.md b/gdk-oci-mysql/06-build-run-app-local/build-run-app-local.md new file mode 100644 index 000000000..7b2318bce --- /dev/null +++ b/gdk-oci-mysql/06-build-run-app-local/build-run-app-local.md @@ -0,0 +1,120 @@ +# Build and Run the Application + +## Introduction + +This lab takes you through the steps to simulate the local development flow and run the application pointing to a local MySQL database running in a container on the same machine. + +![GDK JAR Local MySQL Container](images/gcn-jar-mysql-container.png#input) + +For this, you will start a local MySQL container, and use the Micronaut Maven build plugin to build and run the sample `Genre` application with this local MySQL database. + +Estimated Lab Time: 10 minutes + +### Objectives + +In this lab, you will: + +* Run a MySQL container +* Build and run the application +* Send an HTTP POST request to add a Genre +* Check the Genres present in the MySQL database +* Stop the application + +## Task 1: Run a MySQL container + +1. Open a new terminal in VS Code using the **Terminal>New Terminal** menu. + +2. Copy the following command to run a MySQL container: + + ``` bash + + docker run -it --rm \ + --name "mysql.8" \ + -p 3306:3306 \ + -e MYSQL_DATABASE=db \ + -e MYSQL_USER=sherlock \ + -e MYSQL_PASSWORD=elementary \ + -e MYSQL_ALLOW_EMPTY_PASSWORD=true \ + mysql:8 + + ``` + +3. Place your cursor in the terminal in VS Code and paste (`CTRL+SHIFT+V`) the command you copied. A dialog box will ask **Are you sure you want to paste 8 lines of text in to the terminal?**. Select **Do not ask me again** and click **Paste** to proceed. + + ![VS Code Paste view](./images/paste-mysql-8-confirm.jpg#input) + + Press the enter (return) key. The MySQL container starts in a few seconds. When MySQL is up and running, you will see a similar message in the terminal window: + + ``` bash + ... [Server] /usr/sbin/mysqld: ready for connections. Version: '8.4.3' socket: '/var/run/mysqld/mysqld.sock' port: 3306 MySQL Community Server - GPL. + ``` + +## Task 2: Build and run the application + +1. Open a second terminal in VS Code using the **Terminal>New Terminal** menu. + +2. Run the following command(s): + + + Use `mn:run` to build and start the application on port 8080. Run the application in the background by appending an `&` as shown below. + + ``` bash + + ./mvnw install -pl lib -am && MICRONAUT_ENVIRONMENTS=oraclecloud ./mvnw mn:run -pl oci & + + ``` + + + + Build an executable JAR file and then use `java -jar` to run it. Run the application in the background by appending an `&` as shown below. + + ``` bash + + ./mvnw install -pl lib -am && MICRONAUT_ENVIRONMENTS=oraclecloud ./mvnw package -pl oci + + MICRONAUT_ENVIRONMENTS=oraclecloud java -jar oci/target/oci-db-demo-oci-1.0-SNAPSHOT.jar & + + ``` + + +## Task 3: Send an HTTP POST request to add a Genre + +1. Press the enter (return) key. From the same terminal, add a genre using the command below, and the `genre` table will now contain an entry. + + ``` bash + + curl -X "POST" "http://localhost:8080/genres" -H 'Content-Type: application/json; charset=utf-8' -d '{ "name": "music" }' | jq + + ``` + +## Task 4: Check the Genres present in the MySQL database + +1. Check the `genres` present in the MySQL database using the `/list` endpoint exposed by the application: + + ``` bash + + curl localhost:8080/genres/list | jq + + ``` + +## Task 5: Stop the application + +1. Bring the running application in the foreground: + + ```bash + + fg + + ``` + +2. Once the application is running in the foreground, use `CTRL+C` to stop it. + +Congratulations! You've successfully completed this lab. Your Java application can successfully use the OCI MySQL HeatWave Database instance as its backend, with secrets in OCI Vault. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/06-build-run-app-local/images/gcn-jar-mysql-container.png b/gdk-oci-mysql/06-build-run-app-local/images/gcn-jar-mysql-container.png new file mode 100644 index 000000000..34b9532f2 Binary files /dev/null and b/gdk-oci-mysql/06-build-run-app-local/images/gcn-jar-mysql-container.png differ diff --git a/gdk-oci-mysql/06-build-run-app-local/images/paste-mysql-8-confirm.jpg b/gdk-oci-mysql/06-build-run-app-local/images/paste-mysql-8-confirm.jpg new file mode 100644 index 000000000..a3f7cbad4 Binary files /dev/null and b/gdk-oci-mysql/06-build-run-app-local/images/paste-mysql-8-confirm.jpg differ diff --git a/gdk-oci-mysql/06-build-run-app-local/images/vscode-dont-show-again.png b/gdk-oci-mysql/06-build-run-app-local/images/vscode-dont-show-again.png new file mode 100644 index 000000000..7dfb2cb6c Binary files /dev/null and b/gdk-oci-mysql/06-build-run-app-local/images/vscode-dont-show-again.png differ diff --git a/gdk-oci-mysql/06-build-run-app-local/images/vscode-paste-urls.png b/gdk-oci-mysql/06-build-run-app-local/images/vscode-paste-urls.png new file mode 100644 index 000000000..fbca1fac7 Binary files /dev/null and b/gdk-oci-mysql/06-build-run-app-local/images/vscode-paste-urls.png differ diff --git a/gdk-oci-mysql/07-build-run-native-local/build-run-native-local.md b/gdk-oci-mysql/07-build-run-native-local/build-run-native-local.md new file mode 100644 index 000000000..40674ba5f --- /dev/null +++ b/gdk-oci-mysql/07-build-run-native-local/build-run-native-local.md @@ -0,0 +1,101 @@ +# Build and run a native executable + +## Introduction + +This lab describes how to generate and run a native executable for the application using GraalVM Native Image and connect it to a MySQL Database running in a container. + +You will use [GraalVM Native Image](https://docs.oracle.com/en/graalvm/jdk/17/docs/overview/)’s ahead-of-time compilation to build a native executable for the application. + +At build time, GraalVM analyzes a Java application and its dependencies to identify just what classes, methods, and fields are absolutely necessary, and then generates a native executable with optimized machine code for just these elements. + +Native executables built with GraalVM require less memory, are smaller in size, and start upto 100x faster than just-in-time compiled applications running on a Java Virtual Machine. + +Estimated Lab Time: 15 minutes + +### Objectives + +In this lab, you will: + +* Build and run a native executable for the application +* Send an HTTP POST request to add a Genre +* Check the Genres present in the MySQL database +* Stop the application + +## Task 1: Build and run a native executable for the application + +1. In the second terminal in VS Code, check the version of the GraalVM native-image utility: + + ``` bash + + native-image --version + + ``` + +2. To generate a native executable using Maven, run the following command: + + ``` bash + + ./mvnw install -pl lib -am && MICRONAUT_ENVIRONMENTS=oraclecloud ./mvnw clean package -pl oci -Dpackaging=native-image + + ``` + + It takes around four minutes to generate the native executable. + +3. The native executable is created in the _oci/target_ directory. Run it in the background by appending an `&` as shown below. + + ``` bash + + MICRONAUT_ENVIRONMENTS=oraclecloud oci/target/oci-db-demo-oci & + + ``` + + The native executable starts instantaneously. + +## Task 2: Send an HTTP POST request to add a Genre + +1. Press the enter (return) key. From the same terminal, add a genre using the command below, and the `genre` table will now contain an entry. + ``` bash + + curl -X "POST" "http://localhost:8080/genres" -H 'Content-Type: application/json; charset=utf-8' -d '{ "name": "action" }' | jq + + ``` + +## Task 3: Send an HTTP GET request to fetch all Genres from the database + +1. From the same terminal in VS Code, check the `genres` present in the database using the `/list` endpoint exposed by the application: + + ``` bash + + curl localhost:8080/genres/list | jq + + ``` + +## Task 4: Stop the application + +1. Bring the running application in the foreground: + + ``` bash + + fg + + ``` + +2. Once the application is running in the foreground, use `CTRL+C` to stop it. + +3. Stop the MySQL container started in the previous lab. + + ``` bash + + docker rm -f "mysql.8" + + ``` + +Congratulations! You've successfully completed this lab. Your Java application native executable is now connected to a local MySQL Database running in a container. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/07-build-run-native-local/images/gdk-native-exec-mysql-container.png b/gdk-oci-mysql/07-build-run-native-local/images/gdk-native-exec-mysql-container.png new file mode 100644 index 000000000..ea0376f09 Binary files /dev/null and b/gdk-oci-mysql/07-build-run-native-local/images/gdk-native-exec-mysql-container.png differ diff --git a/gdk-oci-mysql/08-configure-mysql-and-vault/configure-mysql-and-vault.md b/gdk-oci-mysql/08-configure-mysql-and-vault/configure-mysql-and-vault.md new file mode 100644 index 000000000..832465c0d --- /dev/null +++ b/gdk-oci-mysql/08-configure-mysql-and-vault/configure-mysql-and-vault.md @@ -0,0 +1,148 @@ +# Configure the OCI MySQL HeatWave Database instance and the Vault + +## Introduction + +This lab provides instructions to configure the OCI MySQL HeatWave Database instance and the OCI Vault. + +Flyway will create the database tables the first time the application starts, but you must create a database user first. + +Estimated Lab Time: 05 minutes + +### Objectives + +In this lab, you will: + +* Connect to the OCI MySQL HeatWave DB System instance +* Create a MySQL database, a user and password +* Create secrets in the Vault for database user and password + +## Task 1: Connect to the OCI MySQL HeatWave DB System instance + +Set the MySQL Private IP Address value in an environment variable called `MYSQL_IP` for use in subsequent steps. + +1. From the Oracle Cloud Console, navigate to **Databases >> HeatWave MySQL >> DB Systems >> DB System Details**. In the **Connections** tab, under **Primary endpoint**, click **Copy** to copy the **Private IP address**. + + ![MySQL Endpoint Private IP](./images/mysql-endpoint-private-ip.png#input) + +2. From the same terminal in VS Code, set the environment variable `MYSQL_IP` using the `` you copied. + + ```bash + + export MYSQL_IP='' + + ``` + +3. Confirm the value set by running the following command: + + ```bash + + echo $MYSQL_IP + + ``` + +4. Connect to the OCI MySQL HeatWave DB System instance using the private IP Address, the administrator username "mysqladmin" and the password you created earlier. + + >**Note**: If you entered a different administrator username when you created the OCI MySQL DB System instance, replace "mysqladmin" before running the following command: + + ```bash + + mysql --host $MYSQL_IP -u mysqladmin -p + + ``` + + When prompted to enter a password, enter the password you used when you created the OCI MySQL DB System instance. + + You should see the `mysql>` prompt. + +## Task 2: Create a MySQL database, a user and password + +1. From the the `mysql>` prompt, create the database (use any valid database name, for example, “gdkDB”): + + ```bash + + CREATE DATABASE gdkDB; + + ``` + +2. Navigate to the **Compute >> Instances** section in the Oracle Cloud Console, find your compute instances in the list, open it, in the **Instance Details** section find **Primary VNIC**, copy the value of the **Private IPv4 address**. + + ![Copy Compute Instance Private IP](./images/compute-instance-private-ip.png) + +3. Create a database user. Use any valid MySQL username, for example, “guide_user”, and a valid password: + + ```bash + + CREATE USER 'guide_user'@'' IDENTIFIED BY ''; + + ``` + + Replace the text `` with the value you copied. + The `` must be at least eight characters long, with at least one numeric character, one lowercase character, one uppercase character, and one non-alphanumeric character. + +4. Grant access to the database for the new user: + + ```bash + + GRANT ALL ON gdkDB.* TO 'guide_user'@''; + + ``` + +5. Exit the MySQL console: + + ```bash + + exit + + ``` + +## Task 3: Create secrets in the Vault for the database user and password + +1. In the **Vault** you created, navigate to **Secrets**, click **Create Secret**. + +2. Created two secrets - `JDBC_USER` and `JDBC_PASSWORD` - in the your workshop compartment. + +3. Enter the following details: + + ``` + Name: JDBC_USER + + Encryption Key: master-key (Select the master key created in the previous lab) + + Manual secret generation + + Secret Type Template: Plain-Text + + Secret Contents: guide_user + + Show Base64 conversion: YES + ``` + + ![Create JDBC user secret](./images/create-jdbs-user-secret.png) + +4. Enter the following details: + + ``` + Name: JDBC_PASSWORD + + Encryption Key: master-key (Select the master key created in the previous lab) + + Manual secret generation + + Secret Type Template: Plain-Text + + Secret Contents: (Paste the secret value created in the above task) + + Show Base64 conversion: YES + ``` + + ![Create JDBC password secret](./images/create-jdbs-password-secret.png) + +Congratulations! In this section, you created a database, a user and password, and the secrets in OCI Vault. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/08-configure-mysql-and-vault/images/compute-instance-private-ip.png b/gdk-oci-mysql/08-configure-mysql-and-vault/images/compute-instance-private-ip.png new file mode 100644 index 000000000..ff3c3c1b1 Binary files /dev/null and b/gdk-oci-mysql/08-configure-mysql-and-vault/images/compute-instance-private-ip.png differ diff --git a/gdk-oci-mysql/08-configure-mysql-and-vault/images/create-jdbs-password-secret.png b/gdk-oci-mysql/08-configure-mysql-and-vault/images/create-jdbs-password-secret.png new file mode 100644 index 000000000..ee1c6ef1a Binary files /dev/null and b/gdk-oci-mysql/08-configure-mysql-and-vault/images/create-jdbs-password-secret.png differ diff --git a/gdk-oci-mysql/08-configure-mysql-and-vault/images/create-jdbs-user-secret.png b/gdk-oci-mysql/08-configure-mysql-and-vault/images/create-jdbs-user-secret.png new file mode 100644 index 000000000..50d74a5f3 Binary files /dev/null and b/gdk-oci-mysql/08-configure-mysql-and-vault/images/create-jdbs-user-secret.png differ diff --git a/gdk-oci-mysql/08-configure-mysql-and-vault/images/gcn-mysql-service.png b/gdk-oci-mysql/08-configure-mysql-and-vault/images/gcn-mysql-service.png new file mode 100644 index 000000000..3c7b0989b Binary files /dev/null and b/gdk-oci-mysql/08-configure-mysql-and-vault/images/gcn-mysql-service.png differ diff --git a/gdk-oci-mysql/08-configure-mysql-and-vault/images/mysql-endpoint-private-ip.png b/gdk-oci-mysql/08-configure-mysql-and-vault/images/mysql-endpoint-private-ip.png new file mode 100644 index 000000000..ea9d32dcf Binary files /dev/null and b/gdk-oci-mysql/08-configure-mysql-and-vault/images/mysql-endpoint-private-ip.png differ diff --git a/gdk-oci-mysql/09-configure-app/configure-app.md b/gdk-oci-mysql/09-configure-app/configure-app.md new file mode 100644 index 000000000..307370645 --- /dev/null +++ b/gdk-oci-mysql/09-configure-app/configure-app.md @@ -0,0 +1,179 @@ +# Configure the Application to use the OCI MySQL HeatWave Database Instance + +## Introduction + +This lab provides instructions to configure the application to connect to the OCI MySQL HeatWave Database instance using credentials stored as secrets in the OCI Vault. + +The [Micronaut Oracle Cloud](https://micronaut-projects.github.io/micronaut-oracle-cloud/latest/guide/index.html) project provides integration between Micronaut applications and Oracle Cloud, including using Vault as a distributed configuration source. + +Estimated Lab Time: 05 minutes + +### Objectives + +In this lab, you will: + +* Uncomment the Application dependencies +* Configure the Application to read secrets stored in OCI Vault +* Configure OCI Instance Principal Authentication + +## Task 1: Uncomment the Application dependencies + +1. In VS Code, open _oci/pom.xml_. + +2. Uncomment the following snippet in the _pom.xml_ file to add a dependency for `micronaut-oraclecloud-vault` and related OCI SDK dependencies to enable OCI Vault support. + + The `micronaut-oracle-cloud` subproject provides integration between Micronaut applications and Oracle Cloud, including using Vault as a distributed configuration source. + + _oci/pom.xml_ + + ``` xml + + io.micronaut.oraclecloud + micronaut-oraclecloud-httpclient-netty + compile + + + io.micronaut.oraclecloud + micronaut-oraclecloud-vault + compile + + ``` + +## Task 2: Configure the Application to read secrets stored in OCI Vault + +1. Confirm the distributed configuration feature is enabled using the `micronaut.config-client.enabled` flag in the _bootstrap-oraclecloud.properties_ file. + + _oci/src/main/resources/bootstrap-oraclecloud.properties_ + + ```properties + micronaut.config-client.enabled=true + ``` + +2. Uncomment the following snippet in the _bootstrap-oraclecloud.properties_ file. This snippet configures the application to read secrets stored in OCI Vault when the application is running on an OCI Compute Instance. You'll set the value of the externalized configuration variables `VAULT_ID` and `COMPARTMENT_ID` in subsequent steps. + + _oci/src/main/resources/bootstrap-oraclecloud.properties_ + + ```properties + oci.vault.config.enabled=true + # + oci.vault.vaults[0].ocid=${VAULT_ID} + # + oci.vault.vaults[0].compartment-ocid=${COMPARTMENT_ID} + ``` + +3. Navigate to the **Identity & Security >> Compartments** section in the Oracle Cloud Console, find your workshop compartment in the list, open it, in the **Compartment Information** section click **Copy** to copy the value of the Compartment OCID. This is the compartment when you created the secrets. + +4. In the same terminal in VS Code, set the environment variable `COMPARTMENT_ID` using the secrets' compartment OCID you copied. + + ``` + + export COMPARTMENT_ID=ocid1.compartment.oc1... + + ``` + +5. Confirm the value set by running the following command: + + ``` + + echo $COMPARTMENT_ID + + ``` + +6. Navigate to the **Identity & Security >> Vault** section in the Oracle Cloud Console, find your recently created Vault, open it, in the **Vault Information** section click **Copy** to copy the value of the Vault OCID. + +7. In the same terminal in VS Code, set the environment variable `VAULT_ID` using the Vault OCID you copied. + + ``` + + export VAULT_ID=ocid1.vault.oc1... + + ``` + +8. Confirm the value set by running the following command: + + ``` + + echo $VAULT_ID + + ``` + +9. The application uses externalized configuration (`DATASOURCES_DEFAULT_URL`, `JDBC_USER`, and `JDBC_PASSWORD`) to establish a database connection. Here, the application will automatically connect to OCI Vault and retrieve the values of the secrets `JDBC_USER` and `JDBC_PASSWORD` from OCI Vault. The application will use the `DATASOURCES_DEFAULT_URL` set as an environment variable. + + _oci/src/main/resources/application-oraclecloud.properties_ + + ``` properties + datasources.default.url=${DATASOURCES_DEFAULT_URL:`jdbc:mysql://localhost:3306/db`} + datasources.default.username=${JDBC_USER:sherlock} + datasources.default.password=${JDBC_PASSWORD:elementary} + ``` + +10. Set the environment variable `DATASOURCES_DEFAULT_URL` using the MySQL database name you created. + + ```bash + + export DATASOURCES_DEFAULT_URL='jdbc:mysql://'$MYSQL_IP':3306/gdkDB' + + ``` + +11. Confirm the value set by running the following command: + + ``` + + echo $DATASOURCES_DEFAULT_URL + + ``` + +## Task 3: UseConfigure OCI Instance Principal Authentication + +1. In VS Code, open `bootstrap-oraclecloud.properties`. Uncomment the property `oci.config.instance-principal.enabled=true`. The application is configured to use `OCI Instance Principal Authentication` when it is running on an OCI Compute Instance. + + _oci/src/main/resources/bootstrap-oraclecloud.properties_ + + ```properties + oci.config.instance-principal.enabled=true + ``` + + +2. The workshop environment includes a preconfigured `Instance Principal` using a `Dynamic Group` and a `Policy` in OCI to allow the application to read secrets stored in OCI Vault. + + + +2. The following steps show you how to set up an `Instance Principal` using a `Dynamic Group`-less `Policy` in OCI to allow the application to to read secrets stored in OCI Vault. + +3. From the Oracle Cloud Console navigation menu, go to **Identity & Security >> Identity >> Policies**. + + ![Policies Menu](https://oracle-livelabs.github.io/common/images/console/id-policies.png) + +4. Go to your workshop compartment. + +5. Click **Create Policy**. + +6. Enter a name and description. + +7. Select your workshop compartment. + +8. In the **Policy Builder** section, click **Show manual editor**. + +9. Enter the following policy statements in the text area. Replace the placeholders `WORKSHOP_COMPARTMENT_NAME` with your workshop compartment name, and `WORKSHOP_COMPARTMENT_OCID` with your workshop compartment OCID. + + ```text + + Allow any-user to read secret-family in compartment WORKSHOP_COMPARTMENT_NAME where ALL {request.principal.type='instance', request.principal.compartment.id='WORKSHOP_COMPARTMENT_OCID'} + + ``` + + To learn more about access control policies for the Vault, see [Policy Reference - Details for Vault](https://docs.oracle.com/en-us/iaas/Content/Identity/Reference/keypolicyreference.htm). + + + + To learn more about the supported authentication options, see [Micronaut Oracle Cloud Authentication](https://micronaut-projects.github.io/micronaut-oracle-cloud/snapshot/guide/#authentication). + +Congratulations! In this lab, you configured the application to connect to the OCI MySQL HeatWave Database instance using credentials stored as secrets in the OCI Vault. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/09-configure-app/images/adb-copy-ocid.jpg b/gdk-oci-mysql/09-configure-app/images/adb-copy-ocid.jpg new file mode 100644 index 000000000..3128b59da Binary files /dev/null and b/gdk-oci-mysql/09-configure-app/images/adb-copy-ocid.jpg differ diff --git a/gdk-oci-mysql/10-build-run-app/build-run-app.md b/gdk-oci-mysql/10-build-run-app/build-run-app.md new file mode 100644 index 000000000..153980103 --- /dev/null +++ b/gdk-oci-mysql/10-build-run-app/build-run-app.md @@ -0,0 +1,84 @@ +# Build and Run the Application + +## Introduction + +This lab describes how to build and run the application, and use it to connect to the OCI MySQL HeatWave Database instance with secrets in OCI Vault. + +Estimated Lab Time: 10 minutes + +### Objectives + +In this lab, you will: + +* Build and run the application +* Send an HTTP POST request to add a Genre +* Check the Genres present in the MySQL HeatWave Database +* Stop the application + +## Task 1: Build and run the application + +1. In the same terminal in VS Code, run the following command(s): + + + Use `mn:run` to build and start the application on port 8080. Run it in the background by appending an `&` as shown below. + + ``` bash + + ./mvnw install -pl lib -am && MICRONAUT_ENVIRONMENTS=oraclecloud ./mvnw mn:run -pl oci & + + ``` + + + + Build an executable JAR file and then use `java -jar` to run it. Run it in the background by appending an `&` as shown below. + + ``` bash + + ./mvnw install -pl lib -am && MICRONAUT_ENVIRONMENTS=oraclecloud ./mvnw package -pl oci -DskipTests + + MICRONAUT_ENVIRONMENTS=oraclecloud java -jar oci/target/oci-db-demo-oci-1.0-SNAPSHOT.jar & + + ``` + + +## Task 2: Send an HTTP POST request to add a Genre + +1. Press the enter (return) key. From the same terminal, add a genre using the command below, and the `genre` table will now contain an entry. + + ``` bash + + curl -X "POST" "http://localhost:8080/genres" -H 'Content-Type: application/json; charset=utf-8' -d '{ "name": "music" }' | jq + + ``` + +## Task 3: Check the Genres present in the MySQL HeatWave Database + +1. Check the `genres` present in the MySQL database using the `/list` endpoint exposed by the application: + + ``` bash + + curl localhost:8080/genres/list | jq + + ``` + +## Task 4: Stop the application + +1. Bring the running application in the foreground: + + ```bash + + fg + + ``` + +2. Once the application is running in the foreground, use `CTRL+C` to stop it. + +Congratulations! You've successfully completed this lab. Your Java application can successfully use the OCI MySQL HeatWave Database instance as its backend database, with secrets in OCI Vault. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/11-build-run-native/build-run-native.md b/gdk-oci-mysql/11-build-run-native/build-run-native.md new file mode 100644 index 000000000..318b8bb24 --- /dev/null +++ b/gdk-oci-mysql/11-build-run-native/build-run-native.md @@ -0,0 +1,94 @@ +# Build and run a native executable + +## Introduction + +This lab describes how to generate and run a native executable for the application, and use it to connect to the OCI MySQL HeatWave Database instance with secrets in OCI Vault. + +You will use [GraalVM Native Image](https://docs.oracle.com/en/graalvm/jdk/17/docs/overview/)’s ahead-of-time compilation to build a native executable for the application. + +At build time, GraalVM analyzes a Java application and its dependencies to identify just what classes, methods, and fields are absolutely necessary, and then generates a native executable with optimized machine code for just these elements. + +Native executables built with GraalVM require less memory, are smaller in size, and start upto 100x faster than just-in-time compiled applications running on a Java Virtual Machine. + +Estimated Lab Time: 15 minutes + +### Objectives + +In this lab, you will: + +* Build and run a native executable for the application +* Send an HTTP POST request to add a Genre +* Check the Genres present in the MySQL HeatWave Database +* Stop the application + +## Task 1: Build and run a native executable for the application + +1. In the same terminal in VS Code, check the version of the GraalVM native-image utility: + + ``` bash + + native-image --version + + ``` + +2. To generate a native executable using Maven, run the following command: + + ``` bash + + ./mvnw install -pl lib -am && MICRONAUT_ENVIRONMENTS=oraclecloud ./mvnw clean package -pl oci -Dpackaging=native-image + + ``` + + It can take approximately 4-5 minutes to generate the native executable. + +3. The native executable is created in the _oci/target_ directory. Run it in the background by appending an `&` as shown below. + + ``` bash + + MICRONAUT_ENVIRONMENTS=oraclecloud oci/target/oci-db-demo-oci & + + ``` + + The native executable starts instantaneously. + +## Task 2: Send an HTTP POST request to add a Genre + +1. From the same terminal in VS Code, add a genre using the command below. + + ``` bash + + curl -X "POST" "http://localhost:8080/genres" -H 'Content-Type: application/json; charset=utf-8' -d '{ "name": "action" }' | jq + + ``` + +## Task 3: Check the Genres present in the MySQL HeatWave Database + +1. From the same terminal in VS Code, check the `genres` present in the database using the `/list` endpoint exposed by the application: + + ``` bash + + curl localhost:8080/genres/list | jq + + ``` + +## Task 4: Stop the application + +1. Bring the running application in the foreground: + + ```bash + + fg + + ``` + +2. Once the application is running in the foreground, use `CTRL+C` to stop it. + +Congratulations! You've successfully completed this lab. Your Java application native executable is now using the OCI MySQL HeatWave Database instance as its backend, with secrets in OCI Vault. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/12-cleanup/cleanup.md b/gdk-oci-mysql/12-cleanup/cleanup.md new file mode 100644 index 000000000..b8e83d523 --- /dev/null +++ b/gdk-oci-mysql/12-cleanup/cleanup.md @@ -0,0 +1,47 @@ +# Cleanup + +## Introduction + +From the Oracle Cloud Console, clean up the resources provisioned for this workshop. + +Estimated Workshop Time: 05 minutes + +### Objectives + +In this lab, you will: + +* Delete the MySQL HeatWave Database instance +* Delete the two Secrets +* Delete the Master Encryption Key +* Delete the Vault +* Destroy Stack +* Delete the Stack +* Delete the Instance Principals Policy + +## Task 1: Cleanup + +From the Oracle Cloud Console, clean up the resources provisioned for this workshop: + +1. From **Databases** >> **MySQL HeatWave Database** >> **DB Systems**, click **Delete** to delete the MySQL HeatWave Database instance permanently. + +2. From **Identity & Security** >> **Key Management & Secret Management** >> **Vault** >> **Secrets**, use **Delete Secret** to delete both the secrets. + +3. From **Identity & Security** >> **Key Management & Secret Management** >> **Vault** >> **Master Encryption Keys**, use **Delete Key** to delete the master encryption key. + +4. From **Identity & Security** >> **Key Management & Secret Management** >> **Vault**, use **Delete Vault** to delete the vault. + +5. From **Resource Manager** >> **Stacks** >> **Stack Details** screen, run **Destroy** to delete the VCN and the Compute instance. + +6. From **Resource Manager** >> **Stacks** >> **Stack Details** screen, **Delete** the stack. + +7. From **Identity & Security** >> **Identity** >> **Policies**, delete the Instance Principals policy. + +Congratulations! You've successfully completed this lab. + +You may now **proceed to the next lab**. + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) \ No newline at end of file diff --git a/gdk-oci-mysql/13-conclusion/conclusion.md b/gdk-oci-mysql/13-conclusion/conclusion.md new file mode 100644 index 000000000..22be04e2a --- /dev/null +++ b/gdk-oci-mysql/13-conclusion/conclusion.md @@ -0,0 +1,23 @@ +# Conclusion + +In this workshop, you've learnt how to build a Java application with the Graal Development Kit for Micronaut (GDK), OCI MySQL HeatWave Database service and Secrets in OCI Vault. + +With the Graal Development Kit for Micronaut (GDK), you can deploy and run the same application against AWS RDS for MySQL, Google Cloud MySQL Database, and Microsoft Azure Database for MySQL without any code changes. + +You've seen how to use GraalVM Native Image to package and run the application as a native executable. + +Application developers can use the Graal Development Kit for Micronaut (GDK) to build cloud-portable Java applications on Oracle Cloud Infrastructure with Micronaut and GraalVM Native Image. + +## Learn More + +- [Securely Store Database Connection Details in an Oracle Cloud Infrastructure Vault](https://graal.cloud/gdk/gdk-modules/secret-management/micronaut-secrets-oci-mysql/?buildTool=maven&lang=java) +- [Create and Connect a Micronaut Application to an OCI MySQL Database](https://graal.cloud/gdk/gdk-modules/database/micronaut-mysql-database-oci/?buildTool=maven&lang=java) +- [GDK Database (MySQL) Module](https://graal.cloud/gdk/modules/#database) +- [GDK Secret Management Module](https://graal.cloud/gdk/modules/#secret-management) +- [Micronaut Data](https://micronaut-projects.github.io/micronaut-data/latest/guide/) + +## Acknowledgements + +* **Author** - [](var:author) +* **Contributors** - [](var:contributors) +* **Last Updated By/Date** - [](var:last_updated) diff --git a/gdk-oci-mysql/variables/variables.json b/gdk-oci-mysql/variables/variables.json new file mode 100644 index 000000000..9482d6dea --- /dev/null +++ b/gdk-oci-mysql/variables/variables.json @@ -0,0 +1,5 @@ +{ + "author": "Graal Product Management", + "contributors": "Lesia Chaban, Sachin Pikle, Ewan Slater, Kris Foster, Shaun Smith", + "last_updated": "Lesia Chaban, October 2024" + } \ No newline at end of file diff --git a/gdk-oci-mysql/workshops/desktop/index.html b/gdk-oci-mysql/workshops/desktop/index.html new file mode 100644 index 000000000..6acdb69d1 --- /dev/null +++ b/gdk-oci-mysql/workshops/desktop/index.html @@ -0,0 +1,62 @@ + + + + + + + + + Oracle LiveLabs + + + + + + + + + + + + +
+
+
+
+
+
+
+
+ + + + + diff --git a/gdk-oci-mysql/workshops/desktop/manifest.json b/gdk-oci-mysql/workshops/desktop/manifest.json new file mode 100644 index 000000000..163ba5ae5 --- /dev/null +++ b/gdk-oci-mysql/workshops/desktop/manifest.json @@ -0,0 +1,88 @@ +{ + "workshoptitle": "Learn how to build a Java application with the Graal Development Kit for Micronaut, OCI MySQL HeatWave Database service and Secrets in OCI Vault", + "variables": ["../../variables/variables.json"], + "help": "livelabs-help-oci_us@oracle.com", + "tutorials": [ + { + "title": "Introduction", + "description": "The Introduction is always second for LiveLabs. The title and contents menu title match for the Introduction.", + "filename": "../../00-introduction/introduction.md" + }, + { + "title": "Get Started", + "description": "Prerequisites for LiveLabs (Oracle-owned tenancies). The title of the lab and the Contents Menu title (the title above) match for Prerequisite lab. This lab is always first.", + "filename": "https://oracle-livelabs.github.io/common/labs/cloud-login/cloud-login-livelabs2.md" + }, + { + "title": "Get Started with noVNC Remote Desktop", + "description": "Using noVNC Remote Desktop", + "filename": "https://oracle-livelabs.github.io/common/labs/remote-desktop/using-novnc-remote-desktop.md" + }, + { + "title": "Lab 1: Clone the Sample Application Source Code", + "filename": "../../02-git-clone/git-clone.md" + }, + { + "title": "Lab 2: Provision an OCI MySQL HeatWave Database instance", + "filename": "../../03-provision-mysql-db/provision-mysql-db.md" + }, + { + "title": "Lab 3: Provision an OCI Vault", + "filename": "../../04-provision-vault/provision-vault.md" + }, + { + "title": "Lab 4: Review the Application Source Code", + "filename": "../../05-review-code/review-code.md" + }, + { + "title": "Lab 5: Build and run the application against a local MySQL database in a container", + "filename": "../../06-build-run-app-local/build-run-app-local.md", + "type" : { + "mn_run" : "mn:run", + "jar" : "JAR" + } + }, + { + "title": "Lab 6: Build and run a native executable and connect to the local MySQL database", + "filename": "../../07-build-run-native-local/build-run-native-local.md", + "type": "desktop" + }, + { + "title": "Lab 7: Configure the OCI MySQL HeatWave Database instance and the Vault", + "filename": "../../08-configure-mysql-and-vault/configure-mysql-and-vault.md", + "type": "desktop" + }, + { + "title": "Lab 8: Configure the application to use the MySQL HeatWave Database instance and the Vault", + "filename": "../../09-configure-app/configure-app.md", + "type": "desktop" + }, + { + "title": "Lab 9: Build and Run the Application", + "filename": "../../10-build-run-app/build-run-app.md", + "type" : { + "mn_run" : "mn:run", + "jar" : "JAR" + } + }, + { + "title": "Lab 10: Build and Run a Native Executable", + "filename": "../../11-build-run-native/build-run-native.md", + "type": "desktop" + }, + { + "title": "Lab 11: Cleanup", + "filename": "../../12-cleanup/cleanup.md", + "type": "desktop" + }, + { + "title": "Conclusion", + "filename": "../../11-conclusion/conclusion.md" + }, + { + "title": "Need Help?", + "description": "Solutions to Common Problems and Directions for Receiving Live Help", + "filename": "https://oracle-livelabs.github.io/common/labs/need-help/need-help-livelabs.md" + } + ] +} diff --git a/gdk-oci-mysql/workshops/sandbox/index.html b/gdk-oci-mysql/workshops/sandbox/index.html new file mode 100644 index 000000000..6acdb69d1 --- /dev/null +++ b/gdk-oci-mysql/workshops/sandbox/index.html @@ -0,0 +1,62 @@ + + + + + + + + + Oracle LiveLabs + + + + + + + + + + + + +
+
+
+
+
+
+
+
+ + + + + diff --git a/gdk-oci-mysql/workshops/sandbox/manifest.json b/gdk-oci-mysql/workshops/sandbox/manifest.json new file mode 100644 index 000000000..ed69337d3 --- /dev/null +++ b/gdk-oci-mysql/workshops/sandbox/manifest.json @@ -0,0 +1,83 @@ +{ + "workshoptitle": "Learn how to build a Java application with the Graal Development Kit for Micronaut, OCI MySQL HeatWave Database service and Secrets in OCI Vault", + "variables": ["../../variables/variables.json"], + "help": "livelabs-help-oci_us@oracle.com", + "tutorials": [ + { + "title": "Introduction", + "description": "The Introduction is always second for LiveLabs. The title and contents menu title match for the Introduction.", + "filename": "../../00-introduction/introduction.md" + }, + { + "title": "Get Started", + "description": "Prerequisites for LiveLabs (Oracle-owned tenancies). The title of the lab and the Contents Menu title (the title above) match for Prerequisite lab. This lab is always first.", + "filename": "https://oracle-livelabs.github.io/common/labs/cloud-login/cloud-login-livelabs2.md" + }, + { + "title": "Lab 1: Clone the Sample Application Source Code", + "filename": "../../02-git-clone/git-clone.md" + }, + { + "title": "Lab 2: Provision an OCI MySQL HeatWave Database instance", + "filename": "../../03-provision-mysql-db/provision-mysql-db.md" + }, + { + "title": "Lab 3: Provision an OCI Vault", + "filename": "../../04-provision-vault/provision-vault.md" + }, + { + "title": "Lab 4: Review the Application Source Code", + "filename": "../../05-review-code/review-code.md" + }, + { + "title": "Lab 5: Build and run the application against a local MySQL database in a container", + "filename": "../../06-build-run-app-local/build-run-app-local.md", + "type" : { + "mn_run" : "mn:run", + "jar" : "JAR" + } + }, + { + "title": "Lab 6: Build and run a native executable and connect to the local MySQL database", + "filename": "../../07-build-run-native-local/build-run-native-local.md", + "type": "desktop" + }, + { + "title": "Lab 7: Configure the OCI MySQL HeatWave Database instance and the Vault", + "filename": "../../08-configure-mysql-and-vault/configure-mysql-and-vault.md", + "type": "desktop" + }, + { + "title": "Lab 8: Configure the application to use the MySQL HeatWave Database instance and the Vault", + "filename": "../../09-configure-app/configure-app.md", + "type": "desktop" + }, + { + "title": "Lab 9: Build and Run the Application", + "filename": "../../10-build-run-app/build-run-app.md", + "type" : { + "mn_run" : "mn:run", + "jar" : "JAR" + } + }, + { + "title": "Lab 10: Build and Run a Native Executable", + "filename": "../../11-build-run-native/build-run-native.md", + "type": "desktop" + }, + { + "title": "Lab 11: Cleanup", + "filename": "../../12-cleanup/cleanup.md", + "type": "desktop" + }, + { + "title": "Conclusion", + "filename": "../../11-conclusion/conclusion.md" + }, + { + "title": "Need Help?", + "description": "Solutions to Common Problems and Directions for Receiving Live Help", + "filename": "https://oracle-livelabs.github.io/common/labs/need-help/need-help-livelabs.md" + } + ] +} diff --git a/gdk-oci-mysql/workshops/tenancy/index.html b/gdk-oci-mysql/workshops/tenancy/index.html new file mode 100644 index 000000000..6acdb69d1 --- /dev/null +++ b/gdk-oci-mysql/workshops/tenancy/index.html @@ -0,0 +1,62 @@ + + + + + + + + + Oracle LiveLabs + + + + + + + + + + + + +
+
+
+
+
+
+
+
+ + + + + diff --git a/gdk-oci-mysql/workshops/tenancy/manifest.json b/gdk-oci-mysql/workshops/tenancy/manifest.json new file mode 100644 index 000000000..b70ee000d --- /dev/null +++ b/gdk-oci-mysql/workshops/tenancy/manifest.json @@ -0,0 +1,98 @@ +{ + "workshoptitle": "Learn how to build a Java application with the Graal Development Kit for Micronaut, OCI MySQL HeatWave Database service and Secrets in OCI Vault", + "variables": ["../../variables/variables.json"], + "help": "livelabs-help-oci_us@oracle.com", + "tutorials": [ + { + "title": "Introduction", + "description": "The Introduction is always first. The title and contents menu title match for the Introduction.", + "filename": "../../00-introduction/introduction.md" + }, + { + "title": "Get Started", + "description": "This is the prerequisites for customers using Free Trial and Paid tenancies, and Always Free accounts (if applicable). The title of the lab and the Contents Menu title (the title above) match for Prerequisite lab. This lab is always first.", + "filename": "https://oracle-livelabs.github.io/common/labs/cloud-login/pre-register-free-tier-account.md" + }, + { + "title": "Prepare Setup", + "description": "How to download your ORM stack and update security rules for an existing VCN", + "filename": "../../01-prepare-setup/prepare-setup.md" + }, + { + "title": "Environment Setup", + "description": "How to provision the workshop environment and connect to it", + "filename": "https://oracle-livelabs.github.io/common/labs/setup-compute-generic/setup-compute-novnc-ssh.md" + }, + { + "title": "Get Started with noVNC Remote Desktop", + "description": "Using noVNC Remote Desktop", + "filename": "https://oracle-livelabs.github.io/common/labs/remote-desktop/using-novnc-remote-desktop.md" + }, + { + "title": "Lab 1: Clone the Sample Application Source Code", + "filename": "../../02-git-clone/git-clone.md" + }, + { + "title": "Lab 2: Provision an OCI MySQL HeatWave Database instance", + "filename": "../../03-provision-mysql-db/provision-mysql-db.md" + }, + { + "title": "Lab 3: Provision an OCI Vault", + "filename": "../../04-provision-vault/provision-vault.md" + }, + { + "title": "Lab 4: Review the Application Source Code", + "filename": "../../05-review-code/review-code.md" + }, + { + "title": "Lab 5: Build and run the application against a local MySQL database in a container", + "filename": "../../06-build-run-app-local/build-run-app-local.md", + "type" : { + "mn_run" : "mn:run", + "jar" : "JAR" + } + }, + { + "title": "Lab 6: Build and run a native executable and connect to the local MySQL database", + "filename": "../../07-build-run-native-local/build-run-native-local.md", + "type": "tenancy" + }, + { + "title": "Lab 7: Configure the OCI MySQL HeatWave Database instance and the Vault", + "filename": "../../08-configure-mysql-and-vault/configure-mysql-and-vault.md", + "type": "tenancy" + }, + { + "title": "Lab 8: Configure the application to use the MySQL HeatWave Database instance and the Vault", + "filename": "../../09-configure-app/configure-app.md", + "type": "tenancy" + }, + { + "title": "Lab 9: Build and Run the Application", + "filename": "../../10-build-run-app/build-run-app.md", + "type" : { + "mn_run" : "mn:run", + "jar" : "JAR" + } + }, + { + "title": "Lab 10: Build and Run a Native Executable", + "filename": "../../11-build-run-native/build-run-native.md", + "type": "tenancy" + }, + { + "title": "Lab 11: Cleanup", + "filename": "../../12-cleanup/cleanup.md", + "type": "tenancy" + }, + { + "title": "Conclusion", + "filename": "../../13-conclusion/conclusion.md" + }, + { + "title": "Need Help?", + "description": "Solutions to Common Problems and Directions for Receiving Live Help", + "filename": "https://oracle-livelabs.github.io/common/labs/need-help/need-help-freetier.md" + } + ] +} \ No newline at end of file