Overview

This article will guide you in how to serve static resources when running Oracle REST Data Services (ORDS) in Standalone Mode.

Prerequisites

Install ORDS

Before you go any further you’ll need to download and install Oracle REST Data Services. Click here for instructions on how to get ORDS up and running in under 5 minutes.

Configure the document root

ORDS 3.0.1 and later support configuring a document root that can be used to serve arbitrary static resources.

The location of the document root is configured using the --document-root option of the standalone command. For example to point the document root at /var/www/html do the following

java -jar ords.war standalone --document-root /var/www/html

You do not need to specify the --document-root argument on every startup, the value is remembered and will continue to be used on each subsequent launch of standalone mode.

The location pointed to by --document-root must exist and must be readable by the process running ORDS.

Default document root location

If you prefer, you can use the default document root location, which is:

${config.dir}/ords/standalone/doc_root

where ${config.dir} is the location of the ORDS configuration folder. You can check the value of this setting by doing:

java -jar ords.war configdir

The location must exist and must be readable by the process runnning ORDS. The doc_root sub-folder of the standalone folder is not created automatically, you will need to create it manually.

Serving Static Resources

Let’s work through an example of serving static resources using Standalone Mode.

For this example we will assume the following:

  • Standalone Mode is running on localhost and listening on port 8080.
  • The static resoures to be served are located in /var/www/html.

To make this a bit more interesting we’re going to use the Bower package manager to install all the CSS etc that the pages will depend on. To install Bower you will first need to install Node Package Manager (NPM), if you do not have it installed already. The install instructions vary depending on operating system.

If you are using a Mac and have Homebrew installed it’s as simple as:

brew install npm

Once you have npm installed you can install Bower:

npm install -g bower

Yes, we did just use a package manager to install two more package managers!

Create Project Skeleton

Let’s create a basic project. We’re going to skip plenty of steps in a modern front-end build workflow, for instance we’re not going to build our front-end assets using Gulp or Grunt, just to prevent this tutorial getting too long.

First let’s create a folder to work in:

mkdir -p /var/www/html/example
cd /var/www/html/example

Now we are ready to start creating our static html. We’re going to build our example using Bootstrap, so we’ll use Bower to install that:

bower install bootstrap

This will create a folder named bower_components in / var/www/html/example where the bootstrap assets will be stored, the example/ folder will now look like this:

└── bower_components
    ├── bootstrap
    │   ├── Gruntfile.js
    │   ├── LICENSE
    │   ├── README.md
    │   ├── bower.json
    │   ├── dist
    │   ├── fonts
    │   ├── grunt
    │   ├── js
    │   ├── less
    │   ├── package.js
    │   └── package.json
    └── jquery
        ├── MIT-LICENSE.txt
        ├── bower.json
        ├── dist
        └── src

Create the example HTML

Next we can create our sample HTML page, create the following in your favorite text editor and save as /var/www/html/example/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="bower_components/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet">
  </head>
  <body>
    <div class="jumbotron">
     <div class="container">
       <h1>Hello, world!</h1>
       <p>This is an example of serving a static HTML resource.</p>
     </div>
   </div>
  </body>
</html>

Time to test this out, if you haven’t already, start ORDS :

java -jar ords.war

This will start ORDS and cause it launch in Standalone Mode. Look for the following text in the console output to ensure ORDS is serving static content from the correct folder:

INFO: The document root is serving static resources located in: /var/www/html

If you don’t see this message then ensure you’ve completed the steps above to configure the document root.

Now type the following URL in your browser:

http://localhost:8080/example/

A page similar to the following should be displayed:

Browser Screenshot showing above URL

Welcome file support

As the example above shows if a folder contains a file named index.html or index.htm ORDS will serve it when the URL of the folder is requested.

HTML file support

Simiarly if a file with a .html or .htm extension exists within the document root then that file can be accessed without it’s file extension. Let’s try this out, create the following in your favorite text editor and save as /var/www/html/example/pretty-nice.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style>
     h1 {
       font-family: "Helvetica Light","Helvetica Neue",sans-serif;
       color: #000;
       background-color: #9c9c9c;
       background-image:
       linear-gradient(
         45deg,
         #5c5c5c,
         white
       );
       padding: .5em 1em;
       position: absolute;
       bottom: 0;
       width: 100%;
       font-size: 10vw;
       font-weight: 900;
       text-transform: uppercase;
       mix-blend-mode: lighten;
     }
     div {
       height: 100vh;
       background-color: red;
       background-image:
       linear-gradient(
         33deg,
        red,
        white
       );
     }
    </style>
  </head>
  <body>
    <div>
     <h1>Pretty Nice!</h1>
    </div>
  </body>
</html>

Now try the URL of the resource in your browser:

http://localhost:8080/example/pretty-nice

A page similar to the following should be displayed:

HTML without file extension

Note how the URL lacks the .html extension.

The support for welcome files and serving HTML resources without their extension helps mimic how static resources are typically served in production environments.