Share

Application Development

It’s Better with Two

Connect database and application services for a quick start to app development.

By Dan McGhan

March/April 2018

Two of my favorite Oracle Cloud services are Oracle Database Exadata Express Cloud Service (Exadata Express) and Oracle Application Container Cloud. Exadata Express is a fully managed Oracle Database service at an entry-level price point for small-to-medium-sized data, and Oracle Application Container Cloud is a lightweight infrastructure that provides an easy way to deploy apps in Docker containers. In this article, I’ll demonstrate how to connect these two at the most basic level.

What do I mean by “the most basic level”? The demo app will be minimalistic. Typically, I might use Oracle Developer Cloud Service to create a Git repository with an automated build process—but not here. This article will focus only on what’s needed to get Exadata Express and Oracle Application Container Cloud connected. At a high-level, the steps are

  • Create a test app
  • Add Exadata Express client credentials
  • Deploy the app to Oracle Application Container Cloud
  • Add some environment variables to get everything working
Create a Test App

The rest of this article assumes that you have an Oracle Cloud account with access to both Exadata Express and Oracle Application Container Cloud. (If you don’t already have an Oracle Cloud account, you can sign up for a free cloud trial.

To connect and use Exadata Express and Oracle Application Container Cloud, start by creating a new directory named connection-test-app on your local machine.

Now create two files in that directory.

  1. Create a file named manifest.json with the following contents: 
    {
  "runtime":{
    "majorVersion":"8"
  },
  "command": "node index.js",
  "release": {},
  "notes": ""
}

Oracle Application Container Cloud apps often include one or two metadata files. In this case, manifest.json specifies the version of Node.js to run and the command to use to start the application. Note that I’ve specified Node.js 8. This means the async/await constructs that I demonstrated in the last part of the async series can be used in the app.

  1. Create a file named index.js with the following contents: 
     const http = require('http');
const oracledb = require('oracledb');
const dbConfig = {
  user: process.env.EECS_USER,
  password: process.env.EECS_PASSWORD,
  connectString: 'dbaccess'
};
let error;
let user;

async function runConnectionTest() {
  let conn;

  try {
    conn = await oracledb.getConnection(dbConfig);
    const result = await conn.execute('select user from dual');

    user = result.rows[0][0];
    error = null;
  } catch (err) {
    error = err;
  } finally {
    if (conn) {
      try {
        await conn.close();
      } catch (err) {
        console.log(err);
      }
    }
  }
}

runConnectionTest();

http.createServer(function(request, response) {
  response.writeHead(200, {'Content-Type': 'text/plain'});

  if (error === null) {
    response.end('Connection test succeeded. You connected to Exadata Express as ' + user + '!');
  } else if (error instanceof Error) {
    response.write('Connection test failed. Check the settings and redeploy app!\n');
    response.end(error.message);
  } else {
    response.end('Connection test pending. Refresh after a few seconds...');
  }
}).listen(process.env.PORT);

The index.js file contains logic that runs a connection test (lines 11–33) and uses a simple web server to deliver the results of the test (lines 35–46). Note that three environment variables are referenced via process.env. PORT is defined by Oracle Application Container Cloud, but the other environment variables will be created in the last step of this tutorial.

Add Exadata Express Client Credentials

To connect to Exadata Express, you must first enable client access and then download the client credentials. The client credentials are needed to encrypt communication between the client (Node.js, in this case) and the database—something that Exadata Express enforces.

  1. Open a browser and sign in to your Oracle Cloud account. Navigate to the Exadata Express console, select the service instance that you’d like to connect to, and then click Manage.
  2. Figure 1 shows the console’s Manage screen. Click the Client Access link and enable access (if this has not already been done). Then click Client Credentials to download the files needed to make the connection. Before downloading the client credentials, you will be prompted to enter a password. You’ll need the password when you connect to Exadata Express using a Java keystore (such as with Oracle SQL Developer), but not when you connect to the database with Oracle Call Interface (such as with Node.js via node-oracledb).

    opensource figure 1

    Figure 1: Exadata Express console’s Manage screen (with annotations)

    Enter and confirm the password, and then click Download. A file named client_credentials.zip will be downloaded to your machine. Treat the downloaded files securely to prevent unauthorized database access.

  3. Extract the contents of the client_credentials.zip file to a new directory named client_credentials inside the connection-test-app directory created earlier. The contents of connection-test-app should look like the files shown in Figure 2.

    opensource figure 2

    Figure 2: Contents of the connection-test-app directory

  4. Change to the client_credentials directory and open the sqlnet.ora file in a text editor. Change the value of DIRECTORY from ?/network/admin to /u01/app/client_credentials. Note that when you deploy an app to Oracle Application Container Cloud, the app’s files are copied to the /u01/app directory of the container. The sqlnet.ora file must point to the location of the client credentials, which can differ depending on the environment.

Deploy the App

At this point, you can deploy the app to Oracle Application Container Cloud.

  1. Change back to the connection-test-app directory and compress the contents (but not the top-level directory itself) in a new zip file named archive.zip. Use a command such as the following, which should work on Linux and macOS: 
    zip -r archive.zip .

    The resulting archive.zip file, shown in Figure 3, will be deployed to Oracle Application Container Cloud.

    opensource figure 3

    Figure 3: Contents of connection-test-app directory, including the archive.zip file

  2. Return to the browser and navigate to the Oracle Application Container Cloud console (you might need to log in to a different identity domain). Click the Create Application button, as shown in Figure 4.

    opensource figure 4

    Figure 4: Oracle Application Container Cloud console

  3. Select Node as the application platform, as shown in Figure 5.

    opensource figure 5

    Figure 5: Oracle Application Container Cloud application platform choices

  4. Enter eecstest as the Name of the application, use the Upload Archive file picker to select the application archive created in the previous step, and then set the Instances and Memory options to 1, as shown in Figure 6. Click Create to start the deployment process.

    opensource figure 6

    Figure 6: Creating the application

    The app will appear in the list of Oracle Application Container Cloud applications, where you can obtain its URL, as shown in Figure 7.

    opensource figure 7

    Figure 7: List of Oracle Application Container Cloud applications

    If you navigate to that URL in a browser, as shown in Figure 8, you’ll see that the test has failed; this is expected.

    opensource figure 8

    Figure 8: Application test fails

    Just one last task is required to get everything working: adding environment variables.
  5. Return to the Oracle Application Container Cloud console and drill into the eecstest app. Select the Deployments option on the left and click the Add button in the Environment Variables section, as shown in Figure 9.

    opensource figure 9

    Figure 9: Adding environment variables

  6. Enter TNS_ADMIN for the Name and enter $APP_HOME/client_credentials for the Value, as shown in Figure 10, and then click Save.

    opensource figure 10

    Figure 10: Adding the TNS_ADMIN variable

  7. Repeat the previous two steps to create two more environment variables. For the second variable, enter EECS_USER as the Name and for the Value, enter the username of the Exadata Express database user you want to connect with. For the third variable, enter EECS_PASSWORD for the Name and for the Value, enter the password of the database user specified in EECS_USER.
  8. After creating the three environment variables, scroll to the top and click the Apply Edits button, as shown in Figure 11. This will redeploy the application with the new settings.

    opensource figure 11

    Figure 11: Apply edits after adding the environment variables

  9. After the app is deployed, navigate to its URL, where you should see that the connection test has succeeded, as shown in Figure 12.

    opensource figure 12

    Figure 12: Connection test succeeded

As you can see, connecting Exadata Express and Oracle Application Container Cloud isn’t that difficult once you understand what’s involved. When you work with a real app, I recommend keeping the client credentials separate from the application files and any software configuration management tools, such as Git.

If you are developing apps locally, you can point the TNS_ADMIN environment variable to a local copy of the client credentials used for development. When you deploy apps to another environment in Oracle Application Container Cloud, you can use an Oracle Developer Cloud Service build process to download the correct client credentials from a storage service and add them to the app files before deploying them to Oracle Application Container Cloud.

Next Steps

LEARN more about Oracle Database Exadata Express Cloud Service.

LEARN more about Oracle Application Container Cloud.

TRY Oracle Cloud.

Dan McGhan

Dan McGhan is the Oracle developer advocate for JS and HTML5. He enjoys sharing the passion he's developed for JS and HTML5 with others.

DISCLAIMER: We've captured these popular historical magazine articles for your reference. Links etc contained within these article possibly won't work. These articles are provided as-is with no guarantee that the information within them is the best advice for current versions of the Oracle Database.