Deploying and Monitoring Oracle REST Data Services

6 Deploying and Monitoring Oracle REST Data Services

This chapter discusses how to deploy and monitor ORDS.

6.1 Deploying Oracle REST Data Services

To deploy Oracle REST Data Service, you can choose one of the following options:

6.1.1 Serve Commands for Running in Standalone Mode

This section describes the serve command options for running in standalone mode.

Although Oracle REST Data Services supports the Java EE application servers, you also have the option of running it in standalone mode. This section describes how to run Oracle REST Data Services in a standalone mode.

Standalone mode is suitable for development use and is supported in production deployments. Standalone mode, however, has minimal management capabilities when compared to most Java EE application servers and may not have adequate management capabilities for production use in some environments.

6.1.1.1 Non-Interactive Serve CLI

The non-interactive serve CLI reads the standalone settings from the global settings.xml file located in the user-specified configuration folder or the default configuration folder. Some standalone settings contain default values if it is a required setting (for example: http port, context path, and so on.) that does not exist.

$ ords --config <CONFIG_PATH> serve
$ ords --config <CONFIG_PATH> serve --port 8777 --apex-images /path/to/apex/images

Example:

Create the Standalone Settings

Note:

You can configure and start ORDS using the interactive install command.

You can create, update, or delete the standalone settings using the following config CLI command:

ords --config <your configuration folder> config set standalone.context.path /ords
If you are using APEX, then you must provide the path to APEX images as follows:

ords --config <your configuration folder> config set standalone.static.path /path/to/apex/images
If you are using HTTP protocol, then specify the following command:

ords --config /path/to/test/config config set standalone.http.port 8443

If you are using a certificate, then specify the following command:

ords --config <your configuration folder> config set standalone.https.port 8443
ords --config <your configuration folder> config set standalone.https.cert /path/to/certificate/mycert.crt
ords --config <your configuration folder> config set standalone.https.cert.key /path/to/certificate/mycert.key

6.1.1.2 Serve Command Options

Long Option	ShortOption	Description
`--apex-images-context-path <STATIC_CONTEXT_PATH>`		Specifies the context path where APEX static resources are located, defaults to `/i`.
`--certificate <SSL_CERTIFICATE_PATH>`		Sets the certificate file for HTTPS, implies `--secure/--ssl` SSL certificate path. If you are providing the SSL certificate, you must specify the certificate location.
`--config <CONFIG_PATH>`	`c <CONFIG_PATH>`-	Specifies the path to the folder containing the configuration files.
`--context-path <CONTEXT_PATH>`		Sets the first part of the path of the URL from which ORDS is served. Defaults to `/ords`
`--document-root <DOCUMENT_ROOT_PATH>`		Specifies the path from which static files are served at the root of the server. The context path takes priority over static files that have the same name.
`--ip-addresses <INTERFACE_IP>`		Specifies ORDS which interface to bind to, use 0.0.0.0 (The default) to bind to all the network interfaces.
`--key <SSL_KEY_PATH>`		Sets the certificate key to use for HTTPS, implies `--secure/–ssl, requires --certificate`. Specifies the SSL certificate key path. If you are providing the SSL certificate, you must specify the certificate key location.
`--port <PORT>`		Specifies the HTTP listen port, default value is 8080. Set the port on which the server should run.
`--secure`		Specifies HTTPS listen port, default value is 8443. Must specify options `--secure --port <PORT>` to use HTTPS. Starts the server with HTTPS capabilities

6.1.1.3 Converting a Private Key to DER (Linux and Unix)

Usually, you would have created a private key and a Certificate Signing Request before obtaining your signed certificate. The private key needs to be converted into DER in order for Oracle REST Data Services to read it properly.

For example, assume that the original private key was created using the OpenSSL tool with a command similar to either of the following:

openssl req -new -newkey rsa:2048 -nodes -keyout yourdomain.key -out yourdomain.csr

openssl genrsa -out private.em 2048

In this case, you must run a command similar to the following to convert it and remove the encryption: openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt

openssl pkcs8 -topk8 -inform PEM -outform DER -in yourdomain.key -out yourdomain.der -nocrypt

After doing this, you can include the path to yourdomain.der when you are prompted using the install interactive command, or you can modify the following entries in conf/ords/standalone/standalone.properties:

ssl.cert=<path to yourdomain.crt>
ssl.cert.key=<path to yourdomain.der>
ssl.host=yourdomain

Also, ensure that jetty.secure.port is set.

6.1.1.4 Configuring a Doc Root for Non-APEX Static Resources

You can configure a doc root for standalone mode to deploy static resources that are outside the /i folder that is reserved for APEX static resources.

To do so, execute the following command:

ords --config /path/to/conf config set standalone.doc.root /var/www/html .

The preceding example makes any resource located within /var/www/html available under http://server:port/. For example, if the file /var/www/html/hello.txt exists, it will be accessible at http://server:port/hello.txt.

The value specified for standalone.doc.root is stored in ${config.dir}/global/settings.xml in the standalone.doc.root property. If a custom doc root is not specified, then the default doc root value of ${config.dir}/global/doc_root is used. Any file placed within this folder is available at the root context.

This approach has the following features and considerations:

HTML resources can be addressed without their file extension. For example, if a file named hello.html exists in the doc root, it can be accessed at the URI http://server:port/hello.
Attempts to address a HTML resource with its file extension are redirected to the location without an extension. For example, if the URI http://server:port/hello.html is accessed, then the client is redirected to http://server:port/hello.

The usual practice is to serve HTML resources without their file extensions, so this feature facilitates that practice, while the redirect handles the case where the resource is addressed with its file extension.
Index pages for folders are supported. If a folder contains a file named index.html or index.htm, then that file is used as the index page for the folder. For example, if /var/www/html contains /abc/xyz/index.html, then accessing http://server:port/abc/xyz/ displays the contents of index.html.
Addressing a folder without a trailing slash causes a redirect to the URI with a trailing slash. For example, if a client accesses http://server:port/abc/xyz, then the server issues a redirect to http://server:port/abc/xyz/.
Resources are generated with weak etags based on the modification stamp of the file and with a Cache Control header that causes the resources to be cached for 1 hour.

6.1.2 Oracle WebLogic Server

This section describes how to deploy Oracle REST Data Services on Oracle WebLogic Server. It assumes that you have completed the installation process and are familiar with Oracle WebLogic Server. If you are unfamiliar with domains, managed servers, deployment, security, users and roles, refer to your Oracle WebLogic Server documentation.

Topics:

6.1.2.1 About Oracle WebLogic Server

You can download Oracle WebLogic Server from Oracle Technology Network.

To learn more about installing Oracle WebLogic Server, see Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server and Oracle Fusion Middleware Installation Guide for Oracle WebLogic Server.

6.1.2.2 Configuring Oracle APEX Images

This section is only applicable if you are using Oracle APEX. If you are not using Oracle APEX, then you can skip this section that provides details about configuring Oracle APEX Images.

If you are using Oracle APEX, then the Oracle APEX image files for that Oracle APEX version must also be accessible to the end user. It is recommended that you configure the Oracle APEX instance wherever applicable to use the resources from the Oracle Content Network. See knowledge document How to Switch APEX to Use Oracle APEX Static Resources on Content Delivery Network (CDN) support document for the steps to do so. The use of the Oracle CDN may not be feasible when you are using Oracle APEX in a network that restricts internet access. In such a scenario, you must deploy a web application to provide the Oracle APEX image files.

Before you begin, you must identify the directory where you extracted the Oracle APEX distribution. In the following steps, this directory is referred to as <apex directory>. You then define a WebLogic web application which refers to this location and deploy that web application with a context-root value which is the default Oracle APEX image prefix: i.Create a directory which is the source for your web archive. In that directory, create a WEB-INF directory with the following files:

web.xml

<?xml version="1.0" encoding="UTF-8"?>
 
<!DOCTYPE web-app PUBLIC
"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_3.dtd">
 
<web-app>
 <!-- This Web-App leverages the alternate doc-root functionality in WebLogic to serve static content
      For WebLogic refer to the weblogic.xml file in this folder
  -->
</web-app>

weblogic.xml

<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
 <!-- This element specifies the context path the static resources are served from -->
 <context-root>/i</context-root>
 <virtual-directory-mapping>
  <!-- This element specifies the location on disk where the static resources are located -->
  <local-path>/scratch/apex/apex_21.2_en/images</local-path>
  <url-pattern>/*</url-pattern>
 </virtual-directory-mapping>
</weblogic-web-app>

Ensure that the local-path value in the weblogic.xml corresponds to your <apex directory>/images directory.

Where:

<apex directory> is the directory location of Oracle APEX.

Create a Web Application with the web.xml and weblogic.xml files

jar cMf i.war WEB-INF/web.xml WEB-INF/weblogic.xml

The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.

Deploy the i.war file to your WebLogic Server following the deployment steps that are applicable to your WebLogic Server environment. Once deployed, access the following URL to verify that the content is available:

http(s)://hostname:port/i/apex_version.txt

In response, the Oracle APEX version you have configured is displayed.

Tip:

The i.war has a context-root with value /i. This is the default Oracle APEX image prefix. If you have configured Oracle APEX with the different image prefix value, then the context-root must be changed to that value.

6.1.2.3 Launching the Administration Server Console

To launch the Administration Server console:

Start an Administration Server.
Launch the WebLogic Administration Console by typing the following URL in your web browser:
```
http://<host>:<port>/console
```
Where:
- <host> is the DNS name or IP address of the Administration Server.
- <port> is the port on which the Administration Server is listening for requests (port 7001 by default).
Enter your WebLogic Administrator username and password.
If your domain is in Production mode, click the Lock & Edit button on the left-pane below the submenu Change Center. If your domain is in Development mode, this button does not appear.

6.1.2.4 Deploying ORDS on Oracle WebLogic Server

Tip:

The Oracle REST Data Services files, ords.war and i.war, must be available before you start this task.

Note:

When you run ORDS in standalone mode using the ORDS serve command, you can specify the location of the configuration directory.

For deploying the ords.war in a supported container such as WebLogic Server, you must specify the configuration directory location. To do this, use one of the following approaches:

The recommended approach is to generate a Web Application archive file with the configuration directory location specified for that war file.
Set the config.url system property in the managed server so that it applies to all the ORDS deployments.
To generate the war file, use the ords war command.

To set the config.url system property, before starting WebLogic Server, run this command: export JAVA_OPTIONS="-Dconfig.url=/scratch/my_ords_config"

To deploy:

Go to the WebLogic Server Home Page. Below Domain Configuration, select Deployments.

The Summary of Deployments is displayed.
Click Install.
Specify the location of the ords.war file and click Next.

The ords.war file is located in the folder where you unzipped the Oracle REST Data Services ZIP file.

Tip:

WebLogic Server determines the context root from the file name of a WAR archive. If you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/..., then you must rename ords.war to apex.war before the deployment.

The Install Application assistant is displayed.
Select Install this deployment as an application and click Next.
Select the servers and/or clusters to which you want to deploy the application or module and click Next.

Tip:

If you have not created additional Managed Servers or clusters, you do not see this assistant page.
In the Optional Settings, specify the following:
1. Name - Enter:
```
ords
```
2. Security - Select the following:
  
  Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor
3. Source accessibility - Select:
  
  Use the defaults defined by the deployment's targets
Click Next.

A summary page is displayed.
Under Additional configuration, select one of the following:
- Yes, take me to the deployment's configuration - Displays the Configuration page.
- No I will review the configuration later - Returns you to the Summary of Deployments page.
Review the summary of configuration settings that you have specified.
Click Finish.
Repeat the previous steps to deploy the i.war file.

In the optional settings, specify the following:
1. Name - Enter:
```
i
```
2. Security - Select:
  
  Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor
3. Source Accessibility - Select:
  
  Use the defaults defined by the deployment's targets
If your domain is in Production Mode, then on the Change Center click Activate Changes.

Related Topics

6.1.2.5 Configuring WebLogic to Handle HTTP Basic Challenges Correctly

By default WebLogic Server attempts to intercept all HTTP Basic Authentication challenges. This default behavior needs to be disabled for Oracle REST Data Services to function correctly. This is achieved by updating the enforce-valid-basic-auth-credentials flag. The WebLogic Server Administration Console does not display the enforce-valid-basic-auth-credentials setting. You can use WebLogic Scripting Tool (WLST) commands to check, and edit the value in a running server.

The following WLST commands display the domain settings:

connect('weblogic','weblogic','t3://localhost:7001')
cd('SecurityConfiguration')
cd('mydomain') 
ls()

If the domain settings displayed, contains the following entry:

-r--   EnforceValidBasicAuthCredentials             true

Then you must set this entry to false.

To set the entry to false, use the WLST commands as follows:

connect('weblogic', 'weblogic', 't3://localhost:7001')
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')  
set('EnforceValidBasicAuthCredentials','false')
save()
activate()
disconnect()
exit()

Note:

WebLogic Server must be restarted for the new settings to take effect.

In the preceding example:

weblogic is the WebLogic user having administrative privileges
weblogic is the password
mydomain is the domain
The AdminServer is running on the localhost and on port 7001

Related Topics

WebLogic Server Command Reference

6.1.2.6 Verifying the State and Health of ords and i

In the Summary of Deployments, select the Control tab and verify that both the ords and i State are Active and the Health status is OK.

If ords and/or i are not Active, then enable them. In the Deployments table, select the check box next to ords and/or i. Click Start and select Servicing all requests to make them active.

6.1.3 Apache Tomcat

This section describes how to deploy Oracle REST Data Services on Apache Tomcat.

Topics:

6.1.3.1 About Apache Tomcat

Tip:

This section assumes that you have completed the installation process and are familiar with Apache Tomcat. If you are unfamiliar with domains, servers, applications, security, users and roles, see your Apache Tomcat documentation.

You can download Apache Tomcat from:

See Also:

Tomcat 8 Software Downloads

6.1.3.2 Configuring Oracle APEX Images

This section is only applicable if you are using Oracle APEX. If you are not using Oracle APEX, then you can skip this section that provides details about configuring Oracle APEX Images.

The use of the Oracle CDN may not be feasible when using Oracle APEX in a network that restricts internet access. In such a scenario, you must deploy a web application to provide the Oracle APEX image files.

To configure Oracle APEX Images on Apache Tomcat:

Copy the contents of the <apex directory>/images folder to <Tomcat directory>/webapps/i/.

Where:
- <apex directory> is the directory location of the Oracle APEX distribution.
- <Tomcat directory> is the folder where Apache Tomcat is installed.

6.1.3.3 Deploying ORDS on Apache Tomcat

Tip:

The Oracle REST Data Services file ords.war must be available before you start this task.

Note:

When you run ORDS in standalone mode using the ORDS serve command, you can specify the location of the configuration directory.

For deploying the ords.war in a supported container such as Apache Tomcat, you must specify the configuration directory location. To do this, use one of the following approaches:

The recommended approach is to generate a Web Application archive file with the configuration directory location specified for that war file.
Set the config.url system property in the managed server so that it applies to all the ORDS deployments.
To generate the war file, use the ords war command.

To set the config.url system property, before starting Apache Tomcat, run this command: export JAVA_OPTS="-Dconfig.url=/scratch/my_ords_config"

To deploy ORDS on Apache Tomcat:

Move the ords.war file into the webapps folder where Apache Tomcat is installed.

Tip:

Apache Tomcat determines the context root from the file name of a WAR archive. If you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/..., then you must rename ords.war to apex.war before moving it into to the webapps folder.
Access Oracle APEX by typing the following URL in your web browser:
```
http://<hostname>:<port>/ords/
```
Where:
- <hostname> is the name of the server where Apache Tomcat is running.
- <port> is the port number configured for Apache Tomcat application server.

Related Topics

6.1.4 Oracle Cloud Infrastructure

As a cloud user, you can deploy Oracle REST Data Services with high availability on Oracle Cloud Infrastructure.

Topics:

6.1.4.1 About Oracle Cloud Infrastructure

Oracle Cloud Infrastructure (OCI) is a set of complementary cloud services that enable you to build and run a wide range of applications and services in a highly available hosted environment. Oracle Cloud Infrastructure offers high-performance compute capabilities (as physical hardware instances) and storage capacity in a flexible overlay virtual network that is securely accessible from your on-premises network.

6.1.4.2 Configuring ORDS for High Availability on Oracle Cloud Infrastructure

You can choose to use the following configurations for high availability of ORDS on Oracle Cloud Infrastructure. Your requirements might differ from the configurations described in this section.

When you create a VCN, determine the number of CIDR blocks required and the size of each block based on the number of resources that you plan to attach to subnets in the VCN. When you design the subnets, consider your traffic flow and security requirements.
Use Oracle Cloud Guard to proactively monitor and maintain the security of your resources in Oracle Cloud Infrastructure.
For production applications, the Oracle database instance should be adhering to Oracle Maximum Availability Architecture (MAA) deployment model in OCI.
When using RAC with the Oracle Database, ensure that the database connection information used by ORDS is pointing to the SCAN listener and not an individual node.
You can create load balancers with upper and lower bounds to help scale based on the number of requests coming in. It can be as small as 10mbps up to 8000mbps.

6.1.4.3 Advantages of Deploying ORDS with High Availability on Oracle Cloud Infrastructure

Following are the advantages of deploying ORDS on Oracle Cloud Infrastructure:

Compute, load balancers, and Database Cloud Instances can all scale to handle increased load. Additional instances can be quickly created and added to the Load Balancer configuration with the compute or ORDS tier. For Exadata Cloud Service, the X8M platform can not only scale CPU, but also the nodes can be added to the RAC cluster to add additional computing power.
Ensure that your subnet and NSG ingress/egress uses very granular rules. To get access to a compute or database tier, use Bastion as a Service, this ensures that only authorized users can access these instances and is also a much more secure method than exposing SSH ports to the public internet.
For database deployments, adhere to the Oracle Maximum Availability Architecture (MAA) guide.
Auto-scaling and scaling in general for each compute and database tier helps control costs and you need to pay only for what is being used with no excess or wasted CPU, memory, or instances. Using a flexible load balancer can also control costs.

6.2 Monitoring Oracle REST Data Services

Standard Java runtime environment diagnostic and monitoring tools are used to gain an insight on the health of an Monitoring Oracle REST Data Services (ORDS) instance running in Apache Tomcat, WebLogic Server, or a standalone mode. These tools track the memory and CPU usage, stuck threads, and other resources. ORDS provides additional insight through the ORDS instance API. The metrics available through the instance API makes it possible to check the status (valid or invalid) of the database pools and to gauge how the pools are being used. This helps in determining the actual load on the system and inform configuration changes in the future.

Topics:

6.2.1 Enabling the ORDS Instance API

This section explains how to enable the ORDS instance API.

To enable the ORDS instance API:

In settings.xml file or pool.xml file, add instance.api.enabled using the configuration command of ords:
- For global settings.xml: ords –config /path/to/config config set –global instance.api.enabled true
- For specific pool.xml: ords –config /path/to/config config –db-pool mypool set instance.api.enabled true
Restart ORDS.

6.2.2 Authorization for Using the ORDS Instance API

The System Administrator role is required to use the ORDS instance API. For production environments, it is recommended that a user with this role is configured through the mid-tier.

6.2.3 API Document

An OpenAPI description of the ORDS instance API services is available at http://<server>/ords/_/instance-api/stable/metadata-catalog/openapi.json.

6.2.4 Using the Instance API

The ORDS instance API service neither provides access to the database nor does it require the client to specify a database user for authentication. However, the ORDS instance returns information on the database pools. The instance API can be used as a basic health check service. To get a summary of the number of valid and invalid database pools, send a GET request to /ords/_/instance-api/stable/status. For example: curl --user sysadmin:oracle http://<server>/ords/_/instance-api/stable/status. This service returns a count of valid and invalid pools. It also returns links to additional information with more details on the database pools cache.

ORDS can be deployed as a single instance or in a cluster. In a cluster, you must address each instance directly to get the specific information about that specific instance as the database pool statistics for one instance may differ from the other instance. However, if the load balancer routes to each instance in a round robin basis (as recommended), then every instance will have similar pool statistics.

6.3 Using OpenTelemetry with Oracle REST Data Services

This section describes how to configure ORDS to use OpenTelemetry.

ORDS can be configured to provide telemetry data (metrics, logs, and traces) through OpenTelemetry. OpenTelemetry, also known as OTEL in short, is a vendor-neutral open-source observability framework for instrumenting, generating, collecting, and exporting telemetry data to assist in the analysis and tuning of software systems. As an industry standard it is natively supported by a number of vendors.

Configure ORDS to export telemetry data to an OpenTelemetry compliant collector

Perform the following steps to run ORDS to exports telemetry data to an OpenTelemetry collector:

Download the latest OpenTelemetry Java Agent.
Configure OpenTelemetry Java Agent
See Also:
- Download OpenTelemetry Java agent
- Configure OpenTelemetry Java Agent
Add -javaagent option to JDK_JAVA_OPTIONS for standalone server or CATALINA_OPTS for Tomcat.

The following example configures OpenTelemetry agent to export telemetry data to an OpenTelemetry Collector running on host otel-collector-host and runs ORDS in a standalone mode:

export OTEL_SERVICE_NAME=ords
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector-host:4317
export JDK_JAVA_OPTIONS=-javaagent:/path/to/opentelemetry-javaagent.jar
ords --config /path/to/config serve

In the preceeding example, the Java agent is specified using the Java standard JDK_JAVA_OPTIONS environment variable.

When you deploy ORDS on Apache Tomcat or Oracle WebLogic Server, the same Java Agent and environment variables can be specified. See Apache Tomcat or Oracle WebLogic server documentation for the most appropriate approach to use for that platform.

Note:

The OTEL_xxxx environment variables are described in detail in OpenTelemetry documentation.

See Also: