This document is best viewed in flatdoc format <a name="constants"></a>

Oracle XE & APEX

The goal of the OXAR (pronounced "Oscar") project is to make it easy for developers to quickly build and/or launch a fully functional instance of Oracle XE and APEX. The scripts provided in this project handle the automatic build.

Note: Currently this build lacks a backup script. It is recommended to do your own backup

For more information and to signup for our email list go to oraopensource.com. You can follow the related blogs on this project here.

If you need additional help, there is a How-To video for this installation which walks you through the entire process.

Current Software Versions

App | Version | Description ------ | ------ | ------ Oracle XE | 11.2.0.2.0 | SQLcl | 4.2.0 | Command line SQL APEX | 18.2 | Currently supports APEX 18.x, 5.x and APEX 4.x releases. Just reference the appropriate file in config.properties ORDS | 18.3.0 | Tomcat | 7.0.57 | Node JS | 8.x | APEX Office Print| 3.0 | Currently only supports 5.x. Disable the option to install this add-on if you are installing versions earlier or later than 5.x

Node.js Tools

App | Version | Description ------ | ------ | ------ oracledb | latest | Node.js driver for Oracle pm2 | latest | Process manager for Node.js apps

Supported OS's

This script currently works on the following Linux distributions

OS | Minimum version | Comments ------ | ------ | ------ CentOS | 7 | ~~Oracle Linux~~ | ~~7.2~~ | ~~Fedora~~ | ~~21~~ | ~~Debian~~ | ~~8.0~~ | See #198 for more information ~~Ubuntu~~ | ~~16.04~~ | See #198 for more information

Deployment Options

Option | Description ------ | ------ Native Build | This is the default option and assumes thats you will be running this script on the machine that it will be installed on. Common uses of this is to run in a VM or cloud machine. Vagrant | Vagrant is a tool for building development environments. Some additional configuration is required when running this script with Vagrant. These changes are noted in the documentation Prebuilt Images | Due to licensing issues, we can not provide a prebuilt image or appliance. As such you will need to manually build the VM yourself with the provided scripts. </br></br>If you are using Amazon AWS EC2, please be sure to follow the configuration steps listed here.

Build

You can build your own VM with the following instructions.

Download

Native Build

#Ensure user is currently root
if [ "$(whoami)" != "root" ]; then
  sudo -i
fi

cd /tmp

#Install Git
if [ -n "$(command -v yum)" ]; then
  #RHEL type OS
  yum install git -y
else
  #Debian type OS
  apt-get install git-core
fi

git clone https://github.com/OraOpenSource/oxar.git
cd oxar

Vagrant

Run the following on your host machine (you will need git installed on your host machine):

git clone https://github.com/OraOpenSource/oxar.git
cd oxar

Configure

Regardless of whether you're doing a native or Vagrant based build, you will need to modify the config.properties file prior to running the installation script. At a minimum, you will need to replace the CHANGME tokens to point to the appropriate files. Read below for help on modifying this file. If doing a Vagrant install, you can modify config.properties using your local text editor.

#Hints for vi:
#Type:<esc key>?CHANGEME   to search for CHANGEME
#Once done modifying an entry, hit <esc> and type: n  to search for next entry

vi config.properties

Files

Due to licensing requirements, you must download the Oracle installation files and modify the following parameters in the config file with the location of these files.

Parameter | Description ------ | ------ OOS_ORACLE_FILE_URL | Download OOS_APEX_FILE_URL | Download OOS_ORDS_FILE_URL | Download OOS_SQLCL_FILE_URL | Download This is an optional file

These can be references to files on a web server or to the location on the server. Some examples:

#Assuming the file resided on myserver.com
OOS_ORACLE_FILE_URL=http://myserver.com/oracle-xe-11.2.0-1.0.x86_64.rpm.zip
#Assuming the file is placed in the /tmp folder on the machine
OOS_ORACLE_FILE_URL=file:///tmp/oracle-xe-11.2.0-1.0.x86_64.rpm.zip

You can copy files from your local machine to the remote server easily using scp. Example:

scp oracle-xe-11.2.0-1.0.x86_64.rpm.zip username@servername.com:/tmp

File Help

To assist getting your Oracle installation files configured for OXAR one approach is to use Dropbox. Once you have downloaded the install files, store them on dropbox and then reference them using the Shared Link feature. Note that you need to change the ...?dl=0 to a ...?dl=1 at the end of the file. For copyright purposes you should only use these links for your OXAR install and not share them publicly.

Instead of having to use vi to edit the file you can use sed to find and replace. An example is as follows: (Note: the escaping of forward slashes (/) in the URL)

sed -i 's/OOS_ORACLE_FILE_URL=CHANGEME/OOS_ORACLE_FILE_URL=https:\/\/www.dropbox.com\/s\/SHAREDLINKCODE\/oracle-xe-11.2.0-1.0.x86_64.rpm.zip?dl=1/g' config.properties
sed -i 's/OOS_APEX_FILE_URL=CHANGEME/OOS_APEX_FILE_URL=https:\/\/www.dropbox.com\/s\/SHAREDLINKCODE\/apex_5.0.3_en.zip?dl=1/g' config.properties
sed -i 's/OOS_ORDS_FILE_URL=CHANGEME/OOS_ORDS_FILE_URL=https:\/\/www.dropbox.com\/s\/SHAREDLINKCODE\/ords.3.0.2.294.08.40.zip?dl=1/g' config.properties
sed -i 's/OOS_SQLCL_FILE_URL=/OOS_SQLCL_FILE_URL=https:\/\/www.dropbox.com\/s\/SHAREDLINKCODE\/sqlcl-4.2.0.16.049.0843-no-jre.zip?dl=1/g' config.properties

Files-Vagrant

Vagrant automatically maps your current folder to /vagrant on its VM. You can copy your files to the subdirectory files in oraclexe_apex (on your host machine) and reference them with /vagrant/files/<filename>. The files subdirectory has been added to .gitignore to exclude the installation files from version control.

Example:

OOS_ORACLE_FILE_URL=file:///vagrant/files/oracle-xe-11.2.0-1.0.x86_64.rpm.zip

Modules

You can optionally chose which modules you want installed. This install supports the following optional modules which can be modified in config.properties

Module | Default | Description ------ | ------ | ------ OOS_MODULE_ORACLE | Y | Install Oracle XE OOS_MODULE_APEX | Y | Install's APEX and all of it's components (Tomcat, ORDS, etc)

APEX

There are additional APEX configurations that you may want to make in the scripts/apex_config.sql file. You can run them later on or manually configure them in the APEX admin account.

Vagrant

By default you don't need to configure anything, however you may want to modify various things about your Vagrant machine. To do so, modify Vagrantfile.

Build

To build the server run the following commands. It is very important that you run it starting from the same folder that it resides in.

Native Install

. build.sh

Vagrant

vagrant up

Add-ons

OXAR now supports 3rd party add-ons to be included into OXAR. Current list of add-ons:

Name | Description --- | --- APEX Office Print | Flexible print server for Oracle Application Express (APEX) to generate your Office and PDF-documents in no time and effort - we make printing easy.

Securing the Server

If you use OXAR in a production instance or is available on the internet it is recommended that you lock down certain features. Review our Securing System document.

How to connect

Oracle / SQL*Plus / SQLcl

There are many different ways to connect to Oracle with SQL*Plus. The How to Connect to Oracle document covers them.

Username | Password | Description ------ | ------ | ------ OOS_USER | oracle | User you can use to develop with right away SYS | oracle | SYSTEM | oracle | APEX_PUBLIC_USER | oracle |

To start/stop/restart Oracle run the following commands:

/etc/init.d/oracle-xe start
/etc/init.d/oracle-xe stop
/etc/init.d/oracle-xe restart

APEX

To connect to APEX go to http://<server_name>/ or https://<server_name>/ and it will direct you to the APEX login page.

Workspace | Username | Password | Description ------ | ------ | ------ | ------ INTERNAL | admin | Oracle1! | Workspace administrator account OOS_USER | oos_user | oracle | You can start developing on this account. It is linked to OOS_USER schema

APEX Web Listener

This project uses Node4ORDS as a web listener. The Node4ORDS project provides the ability to serve static content and will provide additional web server functionality. Please read its documentation for more information.

Node4ORDS is installed in `/opt/node4ord