Deploying a node.js application to the Oracle Application Container Cloud Service

This article describes my first steps with the fairly new Oracle Application Container Cloud [Service]. At this point in time, Oracle Application Container Cloud includes Oracle Java SE Cloud Service, which lets you deploy Java applications to the Oracle Cloud, and Oracle Node Cloud Service, which lets you deploy Node.js applications to the Oracle Cloud. In the near future, support will be add for different types of applications, such as Ruby, Python, and PHP. Through Service Bindings to other Oracle PaaS Service instances, it is easy to integrate applications running on the Application Container Cloud with for example a DBaaS instance or the Messaging Cloud Service. I will cover that integration in a follow up article.

This article will show how a simple node.js application is made to run on the Application Container Cloud. This application serves up a static HTML file that contains JavaScript to access a REST API from the browser. This REST API is also implemented by the node.js application and the corresponding REST calls are handled in the Application Container Cloud.

The act of creating an application on Application Container Cloud leads to provisioning of a Docker Container with either a Java SE run time or a Node.js runtime, followed by the deployment of the specified application into that container and starting the application with the start up command specified in the configuration file (manifest.json).

This article follows the development of the Message Board sample application as described in the very clear Oracle tutorial: development of HTML5 and Node.js application for deployment on Application Container Cloud Service . Because the tutorial does a great job of explaining the development of the Node.js application, I will not reiterate those instructions. Instead, I will focus on the configuration files required for deployment and the actual deployment steps.

Preparing the Message Board node.js application for Deployment

After creating the index.html file and the messageBoardServer.js file as outlined in the tutorial, and testing it on a local node.js instance, I made a few relevant chances. I want both the static index.html file as well as the REST API to be served from the Application Container Cloud. This requires two changes:

• the messageBoardServer needs to handle a URL request for the index.html file
• the index.html file should refer to the REST APIs on a relative URL- relative to its own origin because now we assume that the REST API is accessed on the same server that provided the index.html file

The former is established pretty easily by adding a few lines to function handleRequest:

if(request.url === “/index”){
fs.readFile(“index.html”, function (err, data) {
response.writeHead(200, {‘Content-Type’: ‘text/html’});
response.write(data);
response.end();
});
} else {

Here we specify that when the URL is /index (the bit following host and port), a local static file called index.html in the same directory as the messageBoardServer.js file should be read and returned as response.

The second modification is in the index.html file and is simple too: the variable that holds the URL is changed to hold an empty string:

<script>
// var url = “http://localhost:8089″;
// assume that API service is published on same server that is the server of this HTML file
      var url = “”;

 

These two changes can also easily be tested in my local environment. Accessing http://localhost:8089/index will now result in the same html page to be shown as before; this time however not loaded directly from the file system by the browser but served by node.js instead.

Configuration files

In order to deploy the Node.js application to the Application Container Cloud, it needs to be accompanied by two configuration files. One is package.json – a standard in the world of Node.js and especially npm [the node package manager]. The command npm init can be used to run an interactive dialog that produces the initial package.json file for the application. This file can manually be modified and extended. The package.json that my dialog resulted in:

The most important aspects are the name, the version indication and the dependencies list – the latter being empty in this case because there are no external dependencies for this simple application.

The other configuration file is called manifest.json. That file is specific to Application Container Cloud. This manifest.json file specifies how to start your application and the Node.js runtime version to use (at this moment either 0.10 or 0.12). Optionally, you can include notes and a release indication. The release element has child elements – that are optional and will not be interpreted by Application Container Cloud:

• build – User specified value of build.
• commit – User specified value of commit.
• version – Value maintained by user.

 

Once your application has been tested locally, create an archive (.zip, .tgz, .tar.gz file) that includes the application, any dependent libraries, and the  two configuration files package.json and manifest.json.

Here is what the application looks like on my local file system:

The zip file contains the four other files – all at the same level in the same directory.

Deployment of the Node.js application

To deploy an application for the first time to Application Container Cloud, it needs to be created  as new application from the dashboard for this service.

Here is the dashboard with Create dropdown with the two options: Java SE and Node.js. Select the latter:

A popup appears. Enter the name of the new Node.js application. Provide some notes if you like. Change the memory settings or the number of instances if you have specific requirements. The application can be loaded from the Storage Cloud or uploaded from the local file system. Select Upload Application Archive to make use of that last option. Click on choose file, browse for the zip-archive that contains the node.js application. Then click on Create.

During the upload, a text message is shown in the popup.

When the upload is done, the popup disappears and this message is shown:

After acknowledging this message by clicking OK, this page appears:

It gives some insight into what is going on.

You should realize that creating the application also involves provisioning the Docker Container with the Node.js run time environment. I suspect that more is going one because this process took way too long – close to 5 minutes – to only consist of firing up a new Docker Container from an existing image. That is a bit of a pity, because this whole application creation process should be very fast thanks to that Docker infrastructure.

And as provisioning progress, more status details are provided:

After some time, the application creation is complete:

Click on the application URL:

It results in a GET request being sent to the Node.js application. It is handled as it should be: by returning a list of topics as a JSON message.

When /index is added to the URL, the request is resolved by the Node.js application to the static index.html file that was included in the zip-file:

This page contains JavaScript that is run instantly and starts calling the REST API exposed from the Node.js application. This API returns a list of topics.

It also accepts new topics to be added (through POST requests):

The new topic is shown. It can be clicked on, resulting in details for this new topic to be loaded from another REST resource:

and the data is shown:

When a comment is added – yet another POST request to the REST API – it is shown:

 

The REST API calls made from the index.html page in the browser can also be made from other REST clients, such as SoapUI. For example this request that retrieves the details for the newly added topic 126:

Note: these calls require basic authorization to be added to the request – for a valid user account in the Application Container Cloud – the same credentials that I need to use to access the web application (well, the static index.html file) from a browser.

Another example of a call, to retrieve a list of all topics:

 

Application Management in the Cloud Service Console

It is a simple application and not administration is required hopefully. However, we can do some monitoring, inspection of log files and scaling of the environment. Besides, new versions of the application can be deployed.

The Deployments page is fairly important: here we can define Service Bindings to other Oracle PaaS service instances. Here too, environment variables can be set that can be leveraged inside the Node.js application – using the statement process.env.NAME_OF_VARIABLE (such as process.env.PORT).

Here an example of deploying a new version of the application:

After clicking the button Upload New, this popup appears:

After specifying the new application archive, press OK.

The file is processed:

and redeployment takes place:

This step took also very long – probably longer than the initial creation of the application. From my own experiments with Docker containers, I would have expected these operations to take much shorter than they currently do. I assume that this is just an early version symptom that will change over time.

Note: during redeployment, there is a considerable time where the application is not available. At the present, there does not seem to be a ‘production redeployment’ like feature where the current version remains active until the new version of the application takes over:

Log files are available for inspection. Anything written to the console from the Node.js application can be inspected from these files – that are written to the storage container associated with the JCS instance (I presume). At least I need to provide my Storage Cloud Service credentials in order to download the log file:

From the downloaded zip-file I can inspect the logs:

 

Resources

Tutorial for development of HTML5 and Node.js application for deployment on Application Container Cloud Service.

Details on package.json file.

Documentation on Oracle Application Container Cloud

Download the Node.js application: nodeMessageBoard.zip