Installing and Configuring Customer Managed ORDS on Autonomous Database

8 Installing and Configuring Customer Managed ORDS on Autonomous Database

This section explains how to install and configure Customer Managed Oracle REST Data Services (ORDS) on Autonomous Database.

Topics:

8.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.

Installing and configuring a customer managed environment for ORDS is only supported with Autonomous Database.

Note:

A version of Oracle REST Data Services within one major release of what is running in Autonomous Database (Serverless or Dedicated) is required to use a customer managed environment for ORDS with a version closest to that release.
For example:
If your Autonomous Database is currently hosting ORDS version 22.4, then you must be running the latest possible ORDS version with customer managed environment. Maintain the latest version of ORDS as close as possible, for example 23.1 or 22.3 for the best results.

Note:
The latest version of ORDS can be found in the OCI YUM repository and also at ORDS Downloadable Zip File location.

8.2 Preinstallation Tasks

This section describes the preinstallation tasks.

Before you begin:

Download the wallet from your Oracle Autonomous Database instance.
If you are using ORDS with Oracle APEX, then you are required to setup the Oracle APEX static resources.

8.2.1 Downloading Wallet

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.

To download the wallet for the Autonomous Database instance, see Download Client Credentials (Wallets) for the detailed steps.

8.2.2 Oracle APEX Static Resources

This section describes how to set up the APEX static resources.

If you are using ORDS and APEX, then setting up the APEX static resources is mandatory. You can setup the APEX static resources by using the Oracle Content Delivery Network (CDN), or downloading APEX and copying the APEX images folder to your environment.

Oracle recommends using the Oracle Content Delivery Network to setup the APEX static resources. See Customer Managed ORDS on Autonomous Database for detailed instructions.

Note:
You only need to setup APEX static resources once using CDN, then APEX automatically upgrades this for you in the Autonomous Database.
Download APEX and configure APEX static resources.
- Download APEX from the location Oracle APEX Downloads
- Copy the images directory. See Copying the Images Directory
  
  Note:
  You must download, maintain, and upgrade the APEX static resources and ensure that the APEX version that you are using is consistent with the APEX version on the Autonomous Database.

See Also:

Control Oracle APEX Upgrades

8.3 ORDS Command-Line Interface for Customer Managed ORDS

The ORDS Command-Line Interface (CLI) provides the interactive and silent command install adb to automate configuring a Customer Managed ORDS. This includes creating the ORDS configuration in your environment. If you want to use Autonomous Database with Oracle REST Data Services (ORDS) running in a customer managed environment, execute this command. This creates an ORDS runtime database user. ORDS can connect, and provide the privileges to that runtime user. In addition, it creates and provides privileges to the PL/SQL gateway database user used for APEX, PL/SQL Gateway and OWA, and allow connections through the runtime user. The runtime database user and gateway database user are created in the Autonomous Database.

8.3.1 Interactive Install for ADB Command Line Interface

Use the ORDS Command-Line Interface (CLI) to interactively prompt you for the following information to setup your Customer Managed ORDS.

Wallet Path
Net Service Name from tnsnames.ora contained in the wallet zip file
Administrator user
Runtime database user
PL/SQL gateway user
Additional Database Features
Standalone options

Examples:

ords install adb
ords install adb --interactive [OPTIONS]
ords install adb -i [0PTIONS]

8.3.1.1 Customer Managed ORDS Command Options

Option	Description
`admin-user <DATABASE USER>`	The administrator database user with privileges to create users and grant privileges to database users in the Autonomous Database.
`db-pool <POOL NAME>`	The name of the database connection pool.
`db-user <DATABASE USER>`	The ORDS runtime database user.
`gateway-user <DATABASE USER>`	The PLSQL gateway database user that has privileges to access the stored procedures.
`feature-db-api <BOOLEAN>`	Specifies if you want to enable DB API feature. Possible values are `true` or `false`. If the value is set to `true`, then DB API feature is enabled. If the value is set to `false`, then DB API feature is disabled. Returns an error if the specified options are `--feature-sdw true` and `--feature db-api false`.
`feature-rest-enabled-sql <BOOLEAN>`	Specifies if you want to enable REST-Enabled SQL feature. Possible values are `true` or `false`. If the value is set to `true`, then the REST-Enabled SQL feature is enabled. If the value is set to `false`, then the REST-Enabled SQL feature is disabled. Returns an error if the specified options `are --feature-sdw true` and `--feature-rest-enabled-sql false`.
`feature-sdw <BOOLEAN>`	Specifies if you want to enable Database Actions feature. Possible values are true or false. If the value is set to true, then the Database Actions feature is enabled. If the value is set to false, then the Database Actions feature is disabled. If the option is set to true, then the following settings are set to true in the configuration file: `database.api.enabled` `restEnabledSql.active` Returns an error if `--feature-sdw true` and any of following options are specified, and are set to false: `--feature-db-api` `--feature-rest-enabled-sql`
`-h, --help`	Shows usage information for a command.
`-i, --interactive`	Prompts for the required information.
`log-folder <FOLDER>`	Writes the logs in the folder when creating the users and granting privileges to the user. If this option is omitted, then the output is written to standard output.
`password-stdin`	Reads the password value from standard input when redirecting input to a file or here document.
`wallet <PATH>`	The location of the wallet zip file downloaded from Autonomous Database. Returns an error if the wallet is omitted and the `db.wallet.zip.path` setting does not exist in the ORDS configuration.
`wallet-service-name <NET SERVICE NAME>`	The net service name in the `tnsnames.ora` file located in the wallet zip file. If `--wallet-service-name` option is omitted and the setting `db.wallet.zip.service` does not exist in ORDS configuration, then it defaults to `<db>_LOW` that is got from the `tnsnames.ora` file.

8.3.1.2 Interactive Installation Prompts

This section describes the interactive installation prompts to setup your Customer Managed ORDS.

To setup your Customer Managed ORDS, use the ORDS Command-Line Interface (CLI) to interactively prompt you for the information.

Example:

ords install adb --interactive --prompt-password --log-folder <LOG
    FOLDER>

Where:

--prompt-password: prompt you for the runtime database user's password and the gateway database user's passwords
--prompt-password: If this option is omitted, then the passwords are generated.
Special care should be considered for database user’s password. If you plan to use ORDS on multiple servers and use the same runtime database user and gateway database user, then specify the --prompt-password option to ensure that the same passwords are being used.

Table 8-1 Interactive Installation Prompts

PromptNumber	Prompt	Description
1.	`Enter a number to select the database pool to update, or create an additional database pool. The selected (or created) database pool will be used to configure a Customer Managed ORDS. [1] default MYADB_MEDIUM /path/to/myadb/wallet.zip [2] Create an additional database pool Choose [1]:`	Refer to Entering a Number to Select the Database Pool
2.	`Enter the database pool name:`	Refer to Entering the Database Pool Name
3.	`Enter the Autonomous Database Wallet path: /path/to/wallet.zip`	Refer to Entering the Autonomous Database Wallet Path
4.	`Enter a number to select the TNS Network alias to use [1] DEMO_LOW ...service_name=g123_demo_low.adb.oraclecloud.... [2] DEMO_MEDIUM ...service_name= g123_demo_medium.adb.oracleclo... [3] DEMO_HIGH ...service_name= g123_demo_high.adb.oraclecloud... Choose [1]: 2`	Refer to Enter a Number to Select the TNS Network Alias
5.	`Provide database user name with administrator privileges. Enter the administrator username [ADMIN]:`	Enter the Administrator Username
6.	`Enter the database password for ADMIN:`	Enter the Database Password for ADMIN
7.	`Enter the ORDS runtime database username [ORDS_PUBLIC_USER2]:`	Entering the ORDS Runtime Database Username
8.	`Enter the database password for ORDS_PUBLIC_USER2: Confirm password:`	Entering the Database Password for ORDS_PUBLIC_USER2
9.	`Enter the PL/SQL Gateway database username:`	Entering the PL/SQL Gateway Database Username
10.	`Enter the database password for ORDS_PLSQL_GATEWAY2: Confirm password:`	Enter the Database Password for ORDS_PLSQL_GATEWAY2
11.	`Connecting to Autonomous database user: ADMIN TNS Service: DEMO_MEDIUM Retrieving information`
12.	`Enter a number to select additional feature(s) to enable: [1] Database Actions (Enables all features) [2] REST Enabled SQL and Database API [3] REST Enabled SQL [4] Database API [5] None Choose [1]:`	Entering a Number to Select and Enable Additional Feature
13.	`Enter a number to configure and start ORDS in standalone mode [1] Configure and start ORDS in standalone mode [2] Skip Choose [1]:`	Enter a Number to Configure and Start ORDS
14.	`Enter a number to select the protocol [1] HTTP [2] HTTPS Choose [1]: 2`	Entering a Number to Select a Protocol
15.	`Enter the HTTP port [8080]:`	Entering the HTTP Port
16.	`Enter the HTTPS port [8443]:`	Entering the HTTP Port
17.	`Enter the APEX static resources location: /path/to/apex/images`	Entering the APEX Static Resources Location

8.3.1.2.1 Entering a Number to Select the Database Pool

This prompt is displayed, if an ORDS configuration exists and contains database pool(s).

You can select a database pool to update, or create an additional database pool for your Customer Managed ORDS.

If option 2 is selected, then Prompt number 2 is displayed. Otherwise, Prompt number 3 is displayed.

Note:

If this is the first time you are setting up the Customer Managed ORDS, and the ORDS configuration does not exist, then you are prompted for the wallet location. See Prompt number 3.

8.3.1.2.2 Entering the Database Pool Name

Specify the database pool name.

8.3.1.2.3 Entering the Autonomous Database Wallet Path

Specify the location and filename of the downloaded Autonomous Database wallet.

Note:

If this is the first time you are setting up the Customer Managed ORDS, then you are prompted for the wallet location. Otherwise, if an ORDS configuration already exists, then Prompt number 1 is displayed.

8.3.1.2.4 Enter a Number to Select the TNS Network Alias

Select the TNS alias name that was retrieved from the tnsnames.ora file contained in the wallet zip file.

8.3.1.2.5 Enter the Administrator Username

Specify a database user with administrator privileges. Defaults the database user to ADMIN.

8.3.1.2.6 Enter the Database Password for ADMIN

Specify the password for administrator database user.

8.3.1.2.7 Entering the ORDS Runtime Database Username

Specify the ORDS runtime database user. Defaults the database user to ORDS_PUBLIC_USER2.

8.3.1.2.8 Entering the Database Password for ORDS_PUBLIC_USER2

Prompts for the password if --prompt-password option is specified on the command line. Otherwise, the password prompt is not displayed, and the password is generated.

Note:

If the runtime database user does not exist in the Autonomous Database, then the runtime database user is created and granted privileges. If the runtime database user already exists in the Autonomous Database, and the runtime user’s password does not match the password in the Autonomous Database, then the runtime database user password is changed.

8.3.1.2.9 Entering the PL/SQL Gateway Database Username

Specify the ORDS PL/SQL gateway database user.

8.3.1.2.10 Enter the Database Password for ORDS_PLSQL_GATEWAY2

Prompts for the password if --prompt-password option is specified on the command line. Otherwise, the password prompt is not displayed, and the password is generated.

Note:

If the PL/SQL gateway database user does not exist in the Autonomous Database, then the gateway database user is created and granted privileges. If the gateway user already exists in the Autonomous Database, and the gateway user’s password does not match the password in the Autonomous Database, then the gateway database user password is changed..

8.3.1.2.11 Entering a Number to Select and Enable Additional Feature

Select the additional feature that you want to enable.

See Also:

8.3.1.2.12 Enter a Number to Configure and Start ORDS

You can configure ORDS to run in standalone mode. In addition, you can start ORDS in standalone mode after setup is completed for Customer Managed ORDS.

8.3.1.2.13 Entering a Number to Select a Protocol

Select a protocol.

If option 1 is selected, then prompt number 15 is displayed.
If option 2 is selected, then prompt number 16 is displayed.

8.3.1.2.14 Entering the HTTP Port

Specify the HTTP port.

8.3.1.2.15 Entering the HTTPS Port.

Specify the HTTPS port.

8.3.1.2.16 Entering the APEX Static Resources Location

This prompt displays only if you are maintaining the APEX static resources.

Note:

If you are using the Oracle Content Delivery Network for the APEX static resources, then this prompt is not displayed.

See Also:

Oracle APEX Static Resources

8.3.2 Silent Installation of ADB on Command-Line Interface

For silent installation, provide the following command options to setup your Customer Managed ORDS:

Database Pool: If this option is omitted, then the default database pool is used.
Wallet Path: This is required if this option does not exist in the ORDS configuration database pool.
Wallet Service Name: The TNS alias name from tnsnames.ora file contained in the wallet zip file. If this option is omitted, and the setting db.wallet.zip.service does not exist in the ORDS configuration database pool, then the wallet service name defaults to <DB>_LOW.
Administrator username and password (Required)
Runtime database username and password (Required)
PL/SQL gateway username and password (Required)
Additional Database Features

Install ADB Command

ords install adb [OPTIONS]

See Also:

Customer Managed ORDS Command Options

8.3.2.1 Using Input Redirection

This section describes how to redirect the standard input using the Here document or to a file.

Redirect STDIN to a file

Redirect STDIN to a file that contains the password. In the following example, the file must contain three passwords. Each password must be on a separate line.

Example:

ords install adb --admin-user <DATABASE USER> --db-user <DATABASE USER> --gateway-user <DATABASE
      USER> --wallet <PATH> --wallet-service-name <NET SERVICE NAME> --feature-sdw <BOOLEAN> --log-folder
      <FOLDER> --password-stdin < filename.txt

Where the filename.txt contains passwords:

<PASSWORD FOR admin-user>
<PASSWORD FOR db-user>
<PASSWORD FOR gateway-user>

Starting from left to right, the first password belongs to the first user option (--admin-user) on the command line. The second password belongs to the second user option on the command line (--db-user) and the third password belongs to the third user (--gateway-user) option on the command-line.

Redirect Standard Input Using Here Document

Redirect STDIN using the Here document (also known as heredoc) for the password(s). The heredoc consists of the '<<' redirection operator followed by a delimiter token.

Each password must be on a separate line and it is ended by the delimiter token.

Example:

ords install adb --admin-user <DATABASE USER> --db-user <DATABASE USER> --gateway-user <DATABASE USER>  
--wallet <PATH> --wallet-service-name <NET SERVICE NAME> --feature-sdw <BOOLEAN> --log-folder <FOLDER> 
--password-stdin << EOF
<PASSWORD FOR admin-user>
<PASSWORD FOR db-user>
<PASSWORD FOR gateway-user>
EOF

Note:

Once the operation is complete, delete the file or script that contains the passwords.