Oracle Apex On Oci Database
Oracle Apex On Oci Database
Oracle Apex On Oci Database
Revision History
The following revisions have been made to this white paper since its initial publication:
Date Revision
March 15, 2019 Initial publication
You can find the most recent versions of the Oracle Cloud Infrastructure white papers at
https://cloud.oracle.com/iaas/technical-resources.
Overview 4
Installation 5
Step 1: Download the Terraform Script and Configure the Local System for Shell and
Terraform 5
Maintenance 17
Conclusion 17
References 18
Until now, customers have had to perform standard installation steps to install Oracle APEX on
Oracle Cloud Infrastructure Database instances. To simplify this installation, Oracle has released a
Terraform template that fully automates Oracle APEX installation in a customer tenancy. This
paper provides step-by-step guidance for deploying Oracle APEX on Oracle Cloud Infrastructure
Database by using the Terraform template. Although the manual installation process is still
supported, the Terraform template simplifies the process while implementing best practices for
Oracle APEX deployment.
This document assumes that you have a basic understanding of various components of Oracle
Cloud Infrastructure and Oracle APEX, as well as Terraform. For information, see the following
resources:
• Oracle APEX
Overview
Using the steps provided in this paper, you deploy Oracle APEX on the target database and
Oracle REST Data Services as a web listener on a compute VM in your tenancy. At a high level,
the Terraform template performs the following actions:
• Allows access to the Oracle APEX instance and Oracle REST Data Services even if the
target databases are in private networks, removing the requirement to have a public IP on
the database instance.
• Makes it easy to patch and upgrade Oracle REST Data Services independent of the target
databases. To upgrade or patch Oracle REST Data Services, you can simply stop (or
terminate) the Oracle REST Data Services VM and run the Terraform template again with
the latest version of Oracle REST Data Services.
• Use a single installation of Oracle REST Data Services with multiple database instances.
In line with Oracle Cloud Infrastructure security standards, the Terraform script supports
SSL/HTTPS configuration to access Oracle REST Data Services deployment. You can use IP-
based or FQDN-based browser access. IP-based access uses SSL via self-signed certificates,
and FQDN-based access uses Let's Encrypt certificates for SSL encryption. We recommend using
FQDN-based access.
Note: Oracle APEX is a no-cost feature of Oracle Database and is fully supported by Oracle Support for
Oracle Cloud Infrastructure Database deployment. Support for the Terraform template is on a best-effort
basis.
Installation
This section provides the instructions for using the Terraform script to deploy Oracle APEX on the
target database and Oracle REST Data Services as the web listener on a compute VM in your
tenancy.
Learn more about Terraform and the Oracle Cloud Infrastructure Terraform provider.
Variable Description
Service name of the database (for Oracle Multitenant database, the service name of
TF_VAR_target_db_srv_name the PDB)
Note: We don't recommend installing Oracle APEX common in CDB$ROOT.
TF_VAR_web_srv Flag for the web container to be configured: 0 => Jetty, 1 => Tomcat
TF_VAR_InstanceName Host name of the compute instance (not including the domain name)
TF_VAR_com_port Port to be open to access the web server on the compute instance
TF_VAR_Secure_FQDN_access Flag for FQDN access: 0 => FQDN access, 1 => IP address access
Flag for Oracle APEX installation mode: 0 => full development environment, 1 =>
TF_VAR_APEX_install_mode
runtime environment
TF_VAR_URL_tomcat_file
URL of Object Storage for the Tomcat 8.5 tar.gz extension file
(optional)
$ cat env-vars
### Path to keys
PathToYourSshPublicKey=$HOME/.ssh/id_rsa.pub
PathToYourSshPrivateKey=$HOME/.ssh/id_rsa
PathToYourApiPrivateKey=$HOME/.oci/oci_api_key.pem
### Authentication details
export TF_VAR_tenancy_ocid=ocid1.tenancy.oc1..
export TF_VAR_user_ocid=ocid1.user.oc1..
export TF_VAR_fingerprint=29:2a:a4:5c:35:5e:3c:12:f6:50:6f:79:5c:89:b8:5c
export TF_VAR_private_key_path=${PathToYourApiPrivateKey}
### Compartment
export TF_VAR_compartment_ocid=ocid1.compartment.oc1..
### Public/private keys used on the instances
export TF_VAR_ssh_public_key=$(cat ${PathToYourSshPublicKey} 2>/dev/null)
export TF_VAR_ssh_private_key=$(cat ${PathToYourSshPrivateKey} 2>/dev/null)
export TF_VAR_api_private_key=$(cat ${PathToYourApiPrivateKey} 2>/dev/null)
### Log
# export TF_LOG=TRACE
# export TF_LOG_PATH='./terraform.log'
### Target Database
# export TF_VAR_target_db_admin_pw=
export TF_VAR_target_db_ip=10.0.0.24
export TF_VAR_target_db_srv_name=jetty_fqdn.sub03020528440.test.oraclevcn.com
export TF_VAR_target_db_name=`echo $TF_VAR_target_db_srv_name|awk -F. '{print
$1}'`
### Compute Setting
# TF_VAR_region : us-phoenix-1 | us-ashburn-1 | eu-frankfurt-1 | uk-london-1
export TF_VAR_region=uk-london-1
# TF_VAR_AD : 1 | 2 | 3
export TF_VAR_AD=3
export TF_VAR_InstanceOSVersion=7.6
# TF_VAR_URL_ORDS_file : Object Storage URL for ords.war
export TF_VAR_URL_ORDS_file=https://objectstorage.uk-london-1.oraclecloud.com/
# TF_VAR_web_srv : 0 => Jetty, 1 => Tomcat
export TF_VAR_web_srv=0
# TF_VAR_URL_tomcat_file : Object Storage URL for Tomcat 8.5 tar.gz file,
required only when tomcat is used for Web server
export TF_VAR_URL_tomcat_file=
$ ./setup.sh
-------------------------------------------------------------------------
Setting up environment variables to launch a compute instance for ORDS.
Please enter required information below:
-------------------------------------------------------------------------
.
.
.
Enter 0 to run Jetty (ORDS standalone mode), or 1 to run Tomcat []: 1
***** File location on Object Storage *****
Enter the URL for Tomcat 8.5 tar.gz file []: https://objectstorage.uk-london-
1.oraclecloud.com/apache-tomcat-8.5.32.tar.gz
$ cat env-vars
.
.
.
# TF_VAR_web_srv : 0 => Jetty, 1 => Tomcat
export TF_VAR_web_srv=1
# TF_VAR_URL_tomcat_file : Object Storage URL for Tomcat 8.5 tar.gz file,
required only when tomcat is used for Web server
export TF_VAR_URL_tomcat_file=https://objectstorage.uk-london-1.oraclecloud.com
$ ./setup.sh
-------------------------------------------------------------------------
Setting up environment variables to launch a compute instance for ORDS.
Please enter required information below:
-------------------------------------------------------------------------
.
.
.
Enter 0 to access with FQDN (hostname.yourdomain), or 1 to access with public IP
address []: 1
$ cat env-vars
.
.
.
# TF_VAR_Secure_FQDN_access : 0 => Yes(Enabled FQDN access with CA SSL), 1 =>
No(Access w/ IP address)
export TF_VAR_Secure_FQDN_access=1
export TF_VAR_ZoneName=oci-dbaas.tk
FQDN-based access uses the free but authorized certification provider Let's Encrypt for SSL. Let's
Encrypt is one of many options available in the market, and if you want to use another certificate
provider, you can do so.
To automate the process of enabling SSL, the Terraform script uses the acme.sh certificate
management agent listed on the Let's Encrypt ACME Client Implementations page. The process
for acquiring the certificate is explained on the How It Works page.
As described on the How It Works page, there are two options for getting a certificate:
A certificate from Let's Encrypt is valid for three months. Using cron and ACME protocol clients,
automating the certificate renewal is recommended.
$ ./setup.sh
-------------------------------------------------------------------------
Setting up environment variables to launch a compute instance for ORDS.
Please enter required information below:
-------------------------------------------------------------------------
.
.
.
Enter 0 to access with FQDN (hostname.yourdomain), or 1 to access with public IP
address []: 1
$ cat env-vars
.
.
.
# TF_VAR_Secure_FQDN_access : 0 => Yes(Enabled FQDN access with CA SSL), 1 =>
No(Access w/ IP address)
export TF_VAR_Secure_FQDN_access=0
export TF_VAR_ZoneName=oci-dbaas.tk
$ ./setup.sh
-------------------------------------------------------------------------
Setting up environment variables to launch a compute instance for ORDS.
Please enter required information below:
-------------------------------------------------------------------------
.
.
.
$ cat env-vars
.
.
.
# TF_VAR_APEX_install_mode : 0 => Full Environment mode, 1 => Runtime
Environment mode
export TF_VAR_APEX_install_mode=0
• Download the latest versions of Oracle REST Data Services and Oracle APEX and place
them in an Object Storage bucket.
• Configure the network: a virtual cloud network (VCN), subnets, and security lists.
o Create a VCN with a public subnet for the compute VM where Oracle REST Data
Services will be deployed.
Note: You can deploy Oracle REST Data Services on a private subnet, but then it can't be
accessed over the internet unless you also deploy a load balancing instance. The Terraform
script is not designed for this scenario, however, and won't complete successfully. To install
Oracle REST Data Services on a private subnet, you must use a NAT gateway and a service
gateway to meet access requirements for various resources. This approach requires advanced
Oracle Cloud Infrastructure networking knowledge.
o Create an ingress rule on the VM compute subnet for the port (TF_VAR_com_port) on
which Oracle REST Data Services is listening.
o Create an ingress rule on the target database subnet for the port on which the
database is listening.
Note: Your database instance can be on a private subnet, but the compute VM on which Oracle
REST Data Services is deployed must be able to reach the database instance.
• Ensure sufficient limits are available for the compute VM shape on which Oracle REST
Data Services will be deployed.
Note: You can't use this Terraform template with Oracle Autonomous Transaction Processing or
Oracle Autonomous Data Warehouse because of the SYS access requirement. Oracle APEX
support is planned for a future release.
Note: In an Oracle Multitenant environment, the connection string should be to the PDB.
• (Optional) Download the latest version of Tomcat and place it on Object Storage.
2. Verify that the domain you want is available by using the search box on the home page or
by selecting Services > Register a New Domain after signing in.
5. Select the check box for the agreement, and then click Complete Order.
6. Navigate to Services > My Domains and click Manage Domain for the domain that you
purchased.
7. Go to the Manage Freenom DNS tab, and then click Edit Nameservers.
8. Select Use custom nameservers, enter the following Oracle Cloud Infrastructure DNS
name servers, and click Change Nameservers.
• ns1.p68.dns.oraclecloud.net
• ns2.p68.dns.oraclecloud.net
• ns3.p68.dns.oraclecloud.net
• ns4.p68.dns.oraclecloud.net
1. Creates a compute instance (of the shape that you selected) on the public subnet that
you defined in the VCN
2. Downloads the relevant binaries to the compute VM: ords.war, APEX, JDK, Tomcat (if
selected), and acme.sh (FQDN-based access only)
6. (FQDN-based access only) Configures the Oracle Cloud Infrastructure DNS service:
A. Creates a zone
B. Registers an A record for the compute instance and publishes the change
In our testing, the script completed within 30 minutes for any combination of installation options.
Tip: If the script is running perpetually, verify that all the networking prerequisites are met, and then re-run the
script.
Configuring Oracle REST Data Services to Access More Than One Database
Instance
You can configure Oracle REST Data Services to access more than one database instance. The
apex_add_db.sh shell script is bundled with the Terraform script. You must run this script with the
following parameters to configure multiple databases with the same Oracle REST Data Services
installation. This script must be run on the Oracle REST Data Services compute host by the oracle
user (when using a Jetty server) or the tomcat user (when using Tomcat).
Run this script once for each additional database that you want to configure.
https://<compute_IP_address> or <FQDN>:<port>/ords/<database_name>/
Workspace: Internal
User: ADMIN
Password: <SYS_or_database_admin_password>
1. Shut down the compute VM that has Oracle REST Data Services running on it.
2. Re-run the Terraform template with latest Oracle APEX distribution zip file.
3. After you confirm that the installation on the new compute VM is successful, terminate the
older VM.
If you want to remove the Oracle APEX installation, perform the following steps:
2. Run the Terraform script using the Terraform Destroy command. This command
terminates the Oracle REST Data Services compute instance. Following is sample output
of running the script to destroy created resources:
### -- Resource Termination
$ terraform destroy
Conclusion
This paper describes the process of installing Oracle APEX on Oracle Cloud Infrastructure
Database using the Terraform template released by Oracle. This template greatly simplifies the
installation process while implementing best practices for Oracle APEX deployment.
• Creates a compute VM in a public subnet and configures Oracle REST Data Services on
it
This architecture improves security by not exposing the database to the internet, reduces resource
overhead by allowing the same Oracle REST Data Services instance to access multiple Oracle
APEX databases, and greatly simplifies Oracle REST Data Services maintenance tasks by
separating Oracle REST Data Services from the APEX installation.
CONNECT W ITH US
blogs.oracle.com/oracle Copyright © 2019, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only, and the
contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties
facebook.com/oracle or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a
particular purpose. We specifically disclaim any liability with respect to this document, and no contractual obligations are formed either
directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or
twitter.com/oracle mechanical, for any purpose, without our prior written permission.
oracle.com Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and
are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are
trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. 0319