Skip to content

Commit 3a6a3d3

Browse files
markxnelsonmarkxnelson
authored
Add documentation of recommended settings and dependencies (#787)
* dev docs Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>
1 parent c79e3c5 commit 3a6a3d3

File tree

4 files changed

+389
-2
lines changed

4 files changed

+389
-2
lines changed

‎docs-source/spring/content/development/_index.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
This section provides information about how to develop and deploy Spring Boot applications
2+
with the Oracle Backend for Spring Boot and Microservices.
3+
4+
Spring Boot applications can be developed with no special requirements and
5+
be deployed into Oracle Backend for Spring Boot and Microservices. However, if you do opt-in to the platform
6+
services provided and the CLI, you can shorten your development time and avoid unnecessary
7+
work.
8+
9+
Oracle Backend for Spring Boot provides the following services that applications can use:
10+
11+
- An Oracle Autonomous Database instance in which applications can manage relational,
12+
document, spatial, graph and other types of data, can use Transactional Event Queues for
13+
messaging and events using Java Message Service (JMS), Apache Kafka or Representational
14+
State Transfer (REST) interfaces, and even run machine learning (ML) models.
15+
- A Kubernetes cluster in which applications can run with namespaces pre-configured with
16+
Kubernetes Secrets and ConfigMaps for access to the Oracle Autonomous Database instance
17+
associated with the backend.
18+
- An Apache APISIX API Gateway that can be used to expose service endpoints outside the Kubernetes
19+
cluster, to the public internet. All standard Apache APISIX features like traffic management,
20+
monitoring, authentication, and so on, are available for use.
21+
- Spring Boot Eureka Service Registry for service discovery. The API Gateway and monitoring
22+
services are pre-configured to use this registry for service discovery.
23+
- Spring Cloud Config Server to serve externalized configuration information to applications.
24+
This stores the configuration data in the Oracle Autonomous Database
25+
instance associated with the backend.
26+
- Netflix Conductor OSS for running workflows to orchestrate your services.
27+
- Hashicorp Vault for storing sensitive information.
28+
- Spring Admin for monitoring your services.
29+
- Prometheus and Grafana for collecting and visualizing metrics and for alerting.
30+
- Jaeger for distributed tracing. Applications deployed with the Oracle Backend for
31+
Spring Boot and Microservices CLI have the Open Telemetry Collector automatically added as a Java
32+
agent to provide tracing from the application into the Oracle Database.
33+
34+
An integrated development environment is recommended for developing applications. Oracle
35+
recommends Visual Studio Code or IntelliJ.
36+
37+
Java, Maven or Gradle, a version control system (Oracle recommends git), and other
38+
tools may be required during development.

‎docs-source/spring/content/development/project.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
title: "Project Structure"
3+
---
4+
5+
To take advantage of the built-in platform services, Oracle recommends
6+
using the following project structure.
7+
8+
Recommended versions:
9+
10+
* Spring Boot 3.1.5
11+
* Spring Cloud 2022.0.4
12+
* Java 17 or 21
13+
14+
### Dependencies
15+
16+
Oracle recommends adding the following dependencies to your application so that it
17+
can take advantage of the built-in platform services:
18+
19+
```xml
20+
<properties>
21+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
22+
<java.version>17</java.version>
23+
<spring.boot.dependencies.version>3.1.5</spring.boot.dependencies.version>
24+
<spring-cloud.version>2022.0.4</spring-cloud.version>
25+
</properties>
26+
27+
<dependencies>
28+
<dependency>
29+
<groupId>org.springframework.boot</groupId>
30+
<artifactId>spring-boot-starter-web</artifactId>
31+
</dependency>
32+
<dependency>
33+
<groupId>org.springframework.boot</groupId>
34+
<artifactId>spring-boot-starter-actuator</artifactId>
35+
</dependency>
36+
<dependency>
37+
<groupId>io.micrometer</groupId>
38+
<artifactId>micrometer-registry-prometheus</artifactId>
39+
</dependency>
40+
<dependency>
41+
<groupId>org.springframework.cloud</groupId>
42+
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
43+
</dependency>
44+
</dependencies>
45+
46+
<dependencyManagement>
47+
<dependencies>
48+
<dependency>
49+
<groupId>org.springframework.boot</groupId>
50+
<artifactId>spring-boot-dependencies</artifactId>
51+
<version>${spring.boot.dependencies.version}</version>
52+
<type>pom</type>
53+
<scope>import</scope>
54+
</dependency>
55+
<dependency>
56+
<groupId>org.springframework.cloud</groupId>
57+
<artifactId>spring-cloud-dependencies</artifactId>
58+
<version>${spring-cloud.version}</version>
59+
<type>pom</type>
60+
<scope>import</scope>
61+
</dependency>
62+
</dependencies>
63+
</dependencyManagement>
64+
```
65+
66+
### Spring Application Configuration
67+
68+
Oracle recommends the following configuration in order for the application access to
69+
use the built-in services, including the Spring Boot Eureka Service Registry and the
70+
observability tools:
71+
72+
```yaml
73+
spring:
74+
application:
75+
name: account
76+
zipkin:
77+
base-url: ${zipkin.base-url}
78+
79+
eureka:
80+
instance:
81+
hostname: ${spring.application.name}
82+
preferIpAddress: true
83+
client:
84+
service-url:
85+
defaultZone: ${eureka.service-url}
86+
fetch-registry: true
87+
register-with-eureka: true
88+
enabled: true
89+
90+
management:
91+
endpoint:
92+
health:
93+
show-details: always
94+
endpoints:
95+
web:
96+
exposure:
97+
include: "*"
98+
metrics:
99+
tags:
100+
application: ${spring.application.name}
101+
```
102+
103+
The variables in this configuration are automatically injected to your deployment
104+
and pods when you use the Oracle Backend for Spring Boot and Microservices CLI to deploy your application.
105+
106+
#### Data Sources
107+
108+
If your application uses a data source, then add the following configuration. Note that this
109+
example shows Java Persistence API (JPA), if you are using JDBC you should use the appropriate configuration.
110+
111+
```yaml
112+
spring:
113+
jpa:
114+
hibernate:
115+
ddl-auto: validate
116+
properties:
117+
hibernate:
118+
dialect: org.hibernate.dialect.OracleDialect
119+
format_sql: false
120+
show-sql: false
121+
122+
datasource:
123+
url: ${spring.datasource.url}
124+
username: ${spring.datasource.username}
125+
password: ${spring.datasource.password}
126+
driver-class-name: oracle.jdbc.OracleDriver
127+
type: oracle.ucp.jdbc.PoolDataSource
128+
oracleucp:
129+
connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
130+
connection-pool-name: AccountConnectionPool
131+
initial-pool-size: 15
132+
min-pool-size: 10
133+
max-pool-size: 30
134+
```
135+
136+
The variables in this configuration are automatically injected to your deployment
137+
and pods when you use the Oracle Backend for Spring Boot and Microservices CLI to deploy your application.
138+
139+
#### Liquibase
140+
141+
If you are using Liquibase to manage your database schema and data, then you should
142+
add the following dependency:
143+
144+
```xml
145+
<properties>
146+
<liquibase.version>4.24.0</liquibase.version>
147+
</properties>
148+
149+
<dependencies>
150+
<dependency>
151+
<groupId>org.liquibase</groupId>
152+
<artifactId>liquibase-core</artifactId>
153+
<version>${liquibase.version}</version>
154+
</dependency>
155+
</dependencies>
156+
```
157+
158+
Add the following configuration to your Spring application configuration:
159+
160+
```yaml
161+
spring:
162+
liquibase:
163+
change-log: classpath:db/changelog/controller.yaml
164+
url: ${spring.datasource.url}
165+
user: ${liquibase.datasource.username}
166+
password: ${liquibase.datasource.password}
167+
enabled: ${LIQUIBASE_ENABLED:true}
168+
```
169+
170+
The variables in this configuration are automatically injected to your deployment
171+
and pods when you use the Oracle Backend for Spring Boot and Microservices CLI to deploy your application.
172+
When you use the `deploy` command, you must specify the `liquibase-db` parameter and
173+
provide a user with sufficient privileges, generally this will be premissions to create and alter
174+
users and to grant roles and privileges. If your service uses JMS, this use may also
175+
need execute permissions on `dbms.aq_adm`, `dbms.aq_in` and `dbms.aq_jms`.
176+
177+
178+
#### Oracle Transaction Manager for Microservices
179+
180+
If you are using Oracle Transaction Manager for Microservices (MicroTx) to manage
181+
data consistency across microservices data stores, then add the following
182+
dependency:
183+
184+
```xml
185+
<dependency>
186+
<groupId>com.oracle.microtx.lra</groupId>
187+
<artifactId>microtx-lra-spring-boot-starter-3x</artifactId>
188+
<version>23.4.1</version>
189+
</dependency>
190+
```
191+
192+
Add the following configuration to your Spring application configuration:
193+
194+
```yaml
195+
spring:
196+
microtx:
197+
lra:
198+
coordinator-url: http://otmm-tcs.otmm.svc.cluster.local:9000/api/v1/lra-coordinator
199+
propagation-active: true
200+
headers-propagation-prefix: "{x-b3-, oracle-tmm-, authorization, refresh-}"
201+
202+
lra:
203+
coordinator:
204+
url: http://otmm-tcs.otmm.svc.cluster.local:9000/api/v1/lra-coordinator
205+
```

‎docs-source/spring/content/development/setup.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
2+
This page provides details on how to set up your development environment to work with
3+
Oracle Backend for Spring Boot and Microservices.
4+
5+
The following platforms are recommended for a development environment:
6+
7+
- Microsoft Windows 10 or 11, preferrably with Windows Subsystem for Linux 2
8+
- macOS (11 or later recommended) on Intel or Apple silicon
9+
- Linux, for example Oracle Linux, Ubuntu, and so on.
10+
11+
The following tools are recommended for a development environment:
12+
13+
- Integrated Development Environment, for example Visual Studio Code
14+
- Java Development Kit, for example Oracle, OpenJDK, or GraalVM
15+
- Maven or Gradle for build and testing automation
16+
17+
If you wish to test locally or offline, then the following additional tools are recommended:
18+
19+
- A container platform, for example Rancher Desktop
20+
- An Oracle database (in a container)
21+
22+
## Integrated Development Environment
23+
24+
Oracle recommends Visual Studio Code, which you can download [here](https://code.visualstudio.com/), and
25+
the following extensions to make it easier to write and build your code:
26+
27+
- [Spring Boot Extension Pack](https://marketplace.visualstudio.com/items?itemName=pivotal.vscode-boot-dev-pack)
28+
- [Extension Pack for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)
29+
- [Oracle Developer Tools](https://marketplace.visualstudio.com/items?itemName=Oracle.oracledevtools)
30+
31+
You can install these by opening the extensions tab (Ctrl-Shift-X or equivalent) and using the
32+
search bar at the top to find and install them.
33+
34+
## Java Development Kit
35+
36+
Oracle recommends the [Java SE Development Kit](https://www.oracle.com/java/technologies/downloads/#java17)
37+
or [GraalVM](https://www.graalvm.org/downloads/#). Java 17 or 21 are recommended, note that Spring Boot
38+
3.0 requires at least Java 17. If you want to use JVM Virtual Threads, then Java 21 is recommended.
39+
40+
**Note**: If you are using Spring Boot 2.x, then Oracle encourages you to use at least Java 17, unless
41+
you have a specific reason to stay on Java 11. Refer to the [Spring Boot Support](https://spring.io/projects/spring-boot#support)
42+
page for information on support dates for Spring Boot 2.x.
43+
44+
You can download the latest x64 Java 17 Development Kit from
45+
[this permalink](https://download.oracle.com/java/17/latest/jdk-17_linux-x64_bin.tar.gz).
46+
47+
Decompress the archive in your chosen location (for example your home directory) and then add it to your path:
48+
49+
```bash
50+
export JAVA_HOME=$HOME/jdk-17.0.3
51+
export PATH=$JAVA_HOME/bin:$PATH
52+
```
53+
54+
Use the following command to verify it is installed:
55+
56+
```bash
57+
$ java -version
58+
java version "17.0.3" 2022-04-19 LTS
59+
Java(TM) SE Runtime Environment (build 17.0.3+8-LTS-111)
60+
Java HotSpot(TM) 64-Bit Server VM (build 17.0.3+8-LTS-111, mixed mode, sharing)
61+
```
62+
63+
**Note: Native Images:** If you want to compile your Spring Boot microservices into native
64+
images (which was officially supported from Spring Boot 3.0), then you must use GraalVM, which can be
65+
downloaded [from here](https://www.graalvm.org/downloads/).
66+
67+
## Maven
68+
69+
You can use either Maven or Gradle to build your Spring Boot applications. If you prefer Maven, then
70+
follow the steps in this section. If you prefer Gradle, then refer to the next section.
71+
72+
Download Maven from the [Apache Maven website](https://maven.apache.org/download.cgi).
73+
74+
Decompress the archive in your chosen location (for example your home directory) and then add it to your path:
75+
76+
```bash
77+
$ export PATH=$HOME/apache-maven-3.8.6/bin:$PATH
78+
```
79+
80+
Use the following command to verify it is installed (note that your version may give slightly different output):
81+
82+
```bash
83+
$ mvn -v
84+
Apache Maven 3.8.6 (84538c9988a25aec085021c365c560670ad80f63)
85+
Maven home: /home/mark/apache-maven-3.8.6
86+
Java version: 17.0.3, vendor: Oracle Corporation, runtime: /home/mark/jdk-17.0.3
87+
Default locale: en, platform encoding: UTF-8
88+
OS name: "linux", version: "5.10.102.1-microsoft-standard-wsl2", arch: "amd64", family: "unix"
89+
```
90+
91+
## Gradle
92+
93+
Download Gradle using the [instructions on the Gradle website](https://gradle.org/install/).
94+
Spring Boot is compatible with Gradle version 7.5 or later.
95+
96+
Run the following command to verify that Gradle is installed correctly
97+
98+
```bash
99+
$ gradle -v
100+
101+
------------------------------------------------------------
102+
Gradle 7.6
103+
------------------------------------------------------------
104+
105+
Build time: 2022-11-25 13:35:10 UTC
106+
Revision: daece9dbc5b79370cc8e4fd6fe4b2cd400e150a8
107+
108+
Kotlin: 1.7.10
109+
Groovy: 3.0.13
110+
Ant: Apache Ant(TM) version 1.10.11 compiled on July 10 2021
111+
JVM: 17.0.3 (Oracle Corporation 17.0.3+8-LTS-111)
112+
OS: Linux 5.10.102.1-microsoft-standard-WSL2 amd64
113+
```
114+
115+
## Oracle Database in a container for local testing
116+
117+
If you want to run an instance of Oracle Database locally for development and testing, then Oracle
118+
recommends Oracle Database 23c Free. You can start the database in a container with this
119+
command specifying a secure password:
120+
121+
```bash
122+
docker run --name free23c -d \
123+
-p 1521:1521 \
124+
-e ORACLE_PWD=Welcome12345 \
125+
container-registry.oracle.com/database/free:latest
126+
```
127+
128+
**Note**: If you are using testcontainers, then add the following dependency to your application:
129+
130+
```xml
131+
<dependency>
132+
<groupId>org.testcontainers</groupId>
133+
<artifactId>oracle-free</artifactId>
134+
<version>1.19.2</version>
135+
<scope>test</scope>
136+
</dependency>
137+
```

0 commit comments

Comments
 (0)