Automating Build and Deployment of Node application in Oracle Developer Cloud to Application Container Cloud

A familiar story:

• Develop a Node application with one or more developers
• Use Oracle Developer Cloud Service to organize the development work, host the source code and coordinate build jobs and the ensuing deployment
• Run the Node application on Oracle Application Container Cloud

I have read multiple tutorials and blog posts that each seemed to provide a piece of puzzle. This article shows the full story – in its simplest form.

We will:

• Start a new project on Developer Cloud Service
• Clone the Git repository for this new project
• Locally work on the Node application and configure it for Application Container Cloud
• Commit and push the sources to the Git repo
• Create a Build job in Developer Cloud service that creates the zip file that is suitable for deployment; the job is triggered by changes on the master branch in the Git repo
• Create a Deployment linking to an existing Oracle Application Container Cloud service instance; associate the deployment with the build task (and vice versa)
• Run the build job – and verify that the application will be deployed to ACCS
• Add the ACCS Deployment descriptor with the definition of environment variables (that are used inside the Node application)
• Make a change in the sources of the application, commit and push and verify that the live application gets updated

Prerequisites: access to a Developer Cloud Instance and an Application Container Cloud service. Locally access to git and ideally Node and npm.

Sources for this article are in GitHub: https://github.com/lucasjellema/greeting .

Start a new project on Developer Cloud Service

Create the new project greeting in Developer Cloud

After you press Finish, the new project is initialized along with all associated resources and facilities, such as a new Git repository, a Wiki, an Issue store.

When the provisioning is done, the project can be accessed.

 

Locally work on the Node application

Copy the git URL for the source code repository.

Clone the Git repository for this new project

git clone https://lucas.jellema%40amis.nl@developer.us2.oraclecloud.com/developer73410-a512292/s/developer73410-a512292_greeting_19451/scm/greeting.git

Start a new Node application, using npm init:

This will create the package.json file.

To prepare the application for eventual deployment to Application Container Cloud, we need to add the manifest.json file.

We also need to create a .gitignore file, to prevent node_modules from being committed and pushed to Git.

Implement the application itself, in file app.js. This is a very simplistic application – that will handle an incoming request and return a greeting of some sort:

Note how the greeting can be read from an environment variable, just like the port on which the requests should be listened to. When no environment values are provided, defaults are used instead.

Commit and push the sources to the Git repo

The Git repository in the Developer Cloud Service project is empty except for the readme.md when the project is first created:

Now we commit and push the files created locally:

and

A little while later, these sources show up in Developer Cloud Service console:

Create a Build job in Developer Cloud service

To have the application build we can create a build job in Developer Cloud Service that creates the zip file that is suitable for deployment; this zip file needs to contain all sources from Git and all dependencies (all node modules) specified in package.json. The job is triggered by changes on the master branch in the Git repo. Note: the build job ideally should also perform automated tests – such as described by Yannick here.

Specify free-style job. Specify the name – here BuildAndDeploy.

Configure the Git repository that contains the sources to build; this is the repository that was first set up when the project was created.

Configure the build job to be performed whenever sources are committed to (the master branch in) the Git repository:

 

Create a Build Step, of type Execute Shell:

 

Enter the following shell-script commands:

git config –global url.https://github.com/.insteadOf git://github.com/

npm install

zip -r greeting.zip .

This will download all required node modules and package all sources in a single zip-file called greeting.zip.

Define as post build step that the greeting.zip file should be archived. That makes this zip file available as artifact produced by the build job – for use in deployments or other build jobs.

 

Run the job a first time with Build Now.

The console output for running the shell commands is shown. Note that the implicit first steps performed in a build include the retrieval of all sources from the git repositories on to the file system of the build server. The explicit shell commands are executed subsequently – and can make use of these cloned git repo sources.

The build job produces greeting.zip as artifact:

Create a Deployment linking to an existing Oracle Application Container Cloud service instance

The build job produces an artifact that can be deployed to an ACCS instance. We need a Deployment to create an ACCS instance based on that artifact. The Deployment is the bridge between the build artifact and a specific target environment – in this case an ACCS instance.

Specify name of the configuration – for use within Developer Cloud Service – and of the application – that will be used in Application Container Cloud. Specify the type of Deployment – we want On Demand because that type of Deployment can be associated with a Build job to be automatically performed at the end of the build. Specify the Deployment Target – New of type Application Container Cloud.

Provide the connection details for an ACCS instance. Press Test Connection to verify these details.

Upon success, click on Use Connection.

Specify the type of Runtime – Node in this case. Select the Build Job and Artifact to base this Deployment on:

Note: for now, the Deployment is tied to a specific instance of the build job. When add the Deployment as Post Build step to the Build Job, we will always use the artifact produced by that specific build instance.

When the Deployment is saved, it starts to execute the deployment immediately:

In the Application Container Cloud Console, we can see the new Node application greeting being created

After some time (actually, quite some time) the application is deployed and ready to be accessed:

And here is the result of opening the application in  browser

Now associate the build job with the Deployment, in order to have the deployment performed at the end of each successful build:

Go to the Post Build tab, check the box for Oracle Cloud Service Deployment and add a Deployment Task of type Deploy:

Select the Deployment we created earlier:

And press Save to save the changes to the build job’s definition.

 

Run the build job – and verify that the application will be deployed to ACCS (again)

If we now run the build job, as its last action it should perform the deployment:

The ACCS console shows that now we have Version 2.0, deployed just now.

 

Add the ACCS Deployment descriptor with the definition of environment variables

The app.js file contains the line

var greeting = process.env.GREETING || ‘Hello World!’;

This line references the environment variable GREETING – that currently is not set. By defining a deployment descriptor as part of the Deployment definition, we can not only specify the number of instances and their size as well as any Service Bindings and the value of Environment Variables such as GREETING.

 

Add the Deployment Descriptor json:

{

“memory”: “1G”,

“instances”: “1”,

“environment”: {

“GREETING”:”Greetings to you”,

“APPLICATION_PREFIX”:”GRTZ”

}

}

Note: variable APPLICATION_PREFIX is not currently used.

Save and the deployment will be performed again:

When done, the application can be accessed. This time, the greeting returned is the one specified in the the deployment descriptor deployment.json (as environment variable) and picked up by the application at run time (using

process.env.GREETING).

Make a change in the sources of the application and Do the End To End Workflow

If we make a change in the application and commit and push the change to Git then after some time we should be able to verify that the live application gets updated.

Make the change – a new version label and a small change in the text returned by the application.

Then commit the change and push the changes – to the Developer CS Git repo:

 

The changes arrive in the Git repo:

Now the Git repo has been updated, the build job should be triggered:

Some of the console output – showing that deployment has started:

The ACCS Service Console makes it clear too

When the deployment is done, it is clear that the code changes made it through to the running application:

So editing the source code and committing plus pushing to git suffices to trigger the build and redeployment of the application – thanks to the set up made in Developer Cloud Service.

Next Steps

Show how multiple instances of an application each have their own state – and how using an Application Cache can make them share state.

Show how an ACCS application can easily access a DBaaS instance through Service Bindings (and in the case of Node application through the oracle node driver and OCI libraries that come prepackaged with the ACCS Node Runtime.

Show how Oracle Management Cloud APM can be setup as part of an ACCS instance in order to perform application monitoring of applications running on ACCS; probably works for Log Analytics as well.

 

Resources

Sources for this article are available in GitHub: https://github.com/lucasjellema/greeting.

Oracle Community Article by Abhinav Shroff –Oracle Developer Cloud to build and deploy Nodejs REST project on Application Container Cloud

A-Team Chronicle by Yannick Ongena- Automated unit tests with Node.JS and Developer Cloud Services

Article by Fabrizio Marini – Oracle Application Container Cloud & Developer Cloud Service: How to create a Node.js application with DB connection in pool (in cloud) and how to deploy it on Oracle Application Container Cloud (Node.js) using Developer Cloud Service

Create Node.js Applications (Oracle Documentation) – https://docs.oracle.com/en/cloud/paas/app-container-cloud/create-sample-node.js-applications.html

Developer Cloud Service Docs – Managing Releases in Oracle Developer Cloud Service

Oracle Documentation – Creating Meta Files for ACCS deployments – https://docs.oracle.com/en/cloud/paas/app-container-cloud/dvcjv/creating-meta-data-files.html