Installing and Configuring Customer Managed ORDS on Autonomous Database

3.1 About Customer Managed Oracle REST Data Services on Autonomous Database

When you provision an Autonomous Database instance, by default Oracle REST Data Services (ORDS) is preconfigured and available for the instance. With the default ORDS, Oracle performs any required configuration, patching, and maintenance. Additionally, you can also configure Autonomous Database to use ORDS running in a customer managed environment.

When you use the default ORDS on Autonomous Database, you cannot modify any of the ORDS configuration options. For example, with the default configuration, the JDBC connection pools have a maximum of 100 connections and the connections for ORDS are preconfigured to use the LOW database service. Use a customer managed environment if you want manual control of the configuration and management of Oracle REST Data Services. For example, use this option when your applications require larger connection pools or if you need more control over the ORDS configuration options.

When ORDS runs in a customer managed environment, you are responsible for configuration, patching, and maintenance of ORDS in the customer managed environment. After you configure Autonomous Database to use your customer managed ORDS in addition to the existing autonomously managed ORDS, you can route ORDS HTTPS traffic through your environment. The default Autonomous Database web server and ORDS are still running and ORDS traffic goes to the ORDS running in the customer managed environment. This provides an additional and alternative HTTPS solution for Autonomous Database.

Installing and configuring a customer managed environment for ORDS allows you to run ORDS with configuration options that are not possible using the default Oracle managed ORDS available with Autonomous Database.

Note:

Oracle REST Data Services 19.4.6 or higher is required to use a customer managed environment for ORDS with Autonomous Database.
Installing and configuring a customer managed environment for ORDS is currently only supported with Autonomous Database on Shared Exadata Infrastructure.

3.2 Downloading Wallet and Verifying Connection to Autonomous Database

You need to configure ORDS to connect to the Autonomous Database. With Oracle REST Data Services (ORDS) running in a customer managed environment, you need to obtain the Autonomous Database wallet on the system that runs the customer managed ORDS. Perform the following steps to download the wallet and verify the connection to the Autonomous Database:

Download the wallet for the Autonomous Database instance. Alternatively you can use the OCI CLI to generate the wallet. See generate-wallet for information on using the CLI.
Convert the wallet.zip from the previous step to text. The base64 command encodes binary strings into text representations using the base64 encoding format. For example, run the following command:
```
base64 -w 0 wallet_NAME.zip > wallet_NAME.zip.b64
```
This step prepares the wallet as a text file as required for use in the ORDS configuration (instructions for this follow).
Verify that you can connect from the customer managed environment where you are installing and configuring ORDS to your Autonomous Database. For example, using SQLcl and the wallet you download in Step 1, verify the connection as follows:
1. Connect with SQLcl.
  See Also:
  - Connect with Oracle SQLcl Cloud Connection for Autonomous Data Warehouse environment.
  - Connect with Oracle SQLcl Cloud Connection for Autonomous Transaction Processing environment.
2. View the database services and connect to your Autonomous Database from the customer managed environment.
```
SQL> show tns
TNS_ADMIN set to: /var/folders/4r/path/T/oracle_cloud_config_path

Available TNS Entries
---------------------
dbname_high
dbname_low
dbname_medium


SQL> conn admin@dbname_low
Password? (**********?) *****************
Connected.
SQL>
```

3.3 Creating Customer Managed Oracle REST Data Services User Role

To use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment on your Autonomous Database, you must create a user, grant privileges to the user, and run the procedure ORDS_ADMIN.PROVISION_RUNTIME_ROLE.

Perform the following steps to create a user for the ORDS JDBC Connection Pool and prepare the Autonomous Database instance for using Oracle REST Data Services in a customer managed environment:

Connect to your Autonomous Database as the ADMIN user.
Create a new ORDS user and grant the required privileges to the new user as follows:
```
CREATE USER "ORDS_PUBLIC_USER2" IDENTIFIED BY "password";
GRANT "CONNECT" TO "ORDS_PUBLIC_USER2";
```
The new user name ORDS_PUBLIC_USER2 is the recommended user name. This name is not required and you can choose a different user name. If you choose a different user name, then all the corresponding user names in these steps need to use the name you choose, rather than ORDS_PUBLIC_USER2.
Create a database user with the ORDS Developer role, so that it can act as an ORDS Runtime user. Additional changes to the ORDS configuration are required to use a user other than ORDS_PUBLIC_USER. As the ADMIN user, run the following procedure:
```
BEGIN
     ORDS_ADMIN.PROVISION_RUNTIME_ROLE(
         p_user => 'ORDS_PUBLIC_USER2',
         p_proxy_enabled_schemas => TRUE);
END;
/
```
Following are the parameters:
- p_user: The name of the user to be configured.
- p_proxy_enabled_schemas: When set to true, proxy grants are added for any REST enabled schemas.

3.4 Downloading and Configuring Oracle REST Data Services

To use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment you need to install ORDS.

Note:

Oracle REST Data Services 19.4.6 or higher is required for a customer managed environment with Autonomous Database.

Depending on where you install Oracle REST Data Services for your customer managed environment, do the following:

If your customer managed environment for Oracle REST Data Services runs in Oracle Cloud Infrastructure, then use an Oracle YUM repository and perform a YUM install of ORDS.
If your customer managed environment for Oracle REST Data Services runs in some other environment, then download ORDS from the Oracle REST Data Services Download page. See Installing Oracle REST Data Services for more information.

In the location where ORDS is installed, create an ORDS configuration folder (this creates a folder and sets up the ORDS configuration environment and settings). For example:
```
java -jar ords.war configdir ./ORDSConfig_2
```
On Oracle Cloud Infrastructure with Linux with a YUM repository the ORDS configuration folder is: /opt/oracle/ords/config.
Edit the ORDS configuration file created in the preceding step ./ords/conf/apex_pu.xml to add or update the following:
```
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="db.username">ORDS_PUBLIC_USER2</entry>
<entry key="db.password">!password</entry>
<entry key="db.wallet.zip.service">dbname_low</entry>
<entry key="db.wallet.zip"><![CDATA[contents_of_wallet_NAME.zip.b64]]></entry>
</properties>
```
Notes:
- The extra "!" in front of the password causes the password to be encrypted the next time the ORDS service starts.
- The db.wallet.zip entry (contents_of_wallet_NAME.zip.b64) includes the contents of the base64 encoded wallet archive that you prepared previously. Ensure that this text is enclosed in a CDATA block (this is a long string of characters). See Downloading Wallet and Verifying Connection to Autonomous Database for details on how to create the wallet_NAME.zip.b64 file.
- The db.username, specified as ORDS_PUBLIC_USER2 is the database username you previously defined. See Creating Customer Managed Oracle REST Data Services User Role for more information.
Edit ./ords/defaults.xml as required for your ORDS installation. See Understanding Configurable Parameters for more information.
Ensure the plsql gateway is enabled for APEX support:
```
<entry key="plsql.gateway.enabled">true</entry>
```
If you want use ORDS with APEX, then you need to enable the PL/SQL gateway in ORDS.

3.5 Preparing and Starting ORDS

To use customer managed Oracle REST Data Services (ORDS) on Autonomous Database, on the system where ORDS runs you need to perform additional configuration steps and then start ORDS.

Note:

For ORDS running with APEX, perform all the steps starting from Step 1. For ORDS running without APEX, perform the steps starting from Step 3.

In the location where ORDS is installed, install the APEX images.
```
unzip apex_19version.zip
```
Note:
To use your customer managed ORDS environment for APEX, you need to download the APEX images of the APEX version that is currently pre-deployed in Oracle Autonomous Database. You can download the APEX images from Download APEX Images.
Edit the standalone properties to add or edit the static images property:
```
standalone.static.path=/path/to/apex/images
```
Create a wallet_cache folder, so that ORDS stores the Autonomous Database wallet on this folder and uses it while connecting to JDBC. For example:
```
mkdir wallet_cache
```
Start ORDS.
- If your customer managed environment for Oracle REST Data Services runs in Oracle Cloud Infrastructure, then start the ORDS service as follows:
```
/opt/oracle/ords start
```
- If your customer managed environment for Oracle REST Data Services runs in the directory where ORDS is installed, then start the ORDS service as follows:
```
java -Duser.timezone=UTC -Ddb.wallet.cache=wallet_cache -jar ords.war standalone --apex-images images --port 8088
```