Oracle® CloudDeveloping for Oracle Application ContainerCloud Service

E64989-23December 2017

Oracle Cloud Developing for Oracle Application Container Cloud Service,

E64989-23

Copyright © 2015, 2017, Oracle and/or its affiliates. All rights reserved.

Primary Authors: Rebecca Parks, Marilyn Beck, Rob Gray, Michael W. Williams

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are"commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of theprograms, including any operating system, integrated software, any programs installed on the hardware,and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron,the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced MicroDevices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not beresponsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

Audience v

Documentation Accessibility v

Related Resources v

Conventions vi

1 Getting Started with Oracle Application Container Cloud Service

About Your Application and Oracle Application Container Cloud Service 1-1

Typical Workflow for Developing Applications 1-2

2 Creating Your Application

Design Considerations 2-1

Making the Application Configurable at Runtime 2-1

Compiling Native Libraries for Your Application 2-2

3 Sample Applications

4 Packaging Your Application

The Packaging Process 4-1

Making a Standalone Application 4-2

Selecting the Launch Command 4-2

Creating Metadata Files 4-4

Creating the Deployment-Ready Archive 4-8

Preparing a Java EE Web Application for Deployment 4-9

Preparing a Cloud Foundry Application for Deployment 4-11

Preparing a Clustered Application for Deployment 4-12

Preparing a Worker Application for Deployment 4-15

iii

5 Monitoring Your Application

Java Mission Control and Java Flight Recorder 5-1

Retrieving the Application Logs 5-1

6 Troubleshooting Oracle Application Container Cloud Service

iv

Preface

Topics:

• Audience

• Documentation Accessibility

• Related Resources

• Conventions

AudienceThis guide is for developers who want to create new or modify existing applications sothat they can be deployed on Oracle Application Container Cloud Service.

Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit the OracleAccessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic supportthrough My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsif you are hearing impaired.

Related ResourcesSee these Oracle resources:

• Oracle Public Cloud

• Java SE

Java Standard Edition (SE) lets you develop and deploy Java applications todesktop and server environments. See Java Platform, Standard Edition (Java SE).

• Oracle Developer Cloud Service

Oracle Developer Cloud Service is a cloud-based software development Platformas a Service (PaaS) and a hosted environment for your application developmentinfrastructure. It provides an open source standards-based solution to develop,collaborate, and deploy applications within Oracle Cloud. When you subscribe toOracle Application Container Cloud Service, you also get a free entitlement toOracle Developer Cloud Service. You can use Oracle Developer Cloud Service to

v

run application builds and then deploy to Oracle Application Container CloudService. See Deploying an Application to Oracle Application Container Cloud inUsing Oracle Developer Cloud Service.

• Java Flight Recorder

Java Flight Recorder (JFR) generates on-demand detailed recordings of the JavaVirtual Machine (JVM) and the embedded application it’s running. The recordeddata includes an execution profile, garbage collection statistics, optimizationdecisions, object allocation, heap statistics, and latency events for locks and I/O.See the Java Flight Recorder Runtime Guide in the Java ComponentsDocumentation.

• Java Mission Control

The Java Mission Control (JMC) is a set of tools that runs on the JavaDevelopment Kit (JDK) and interacts with a JVM to deliver advanced, unobtrusiveJava monitoring and management. See the Java Mission Control User’s Guide inthe Java Components Documentation.

ConventionsThe following text conventions are used in this document:

Convention Meaning

boldface Boldface type indicates graphical user interface elements associatedwith an action, or terms defined in text or the glossary.

italic Italic type indicates book titles, emphasis, or placeholder variables forwhich you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, codein examples, text that appears on the screen, or text that you enter.

Preface

vi

1Getting Started with Oracle ApplicationContainer Cloud Service

Learn how to design and package applications for Oracle Application Container CloudService.

Topics:

• About Your Application and Oracle Application Container Cloud Service

• Typical Workflow for Developing Applications

About Your Application and Oracle Application ContainerCloud Service

Oracle Application Container Cloud Service lets you deploy Java SE, Node.js, PHP,Python, Ruby, Go, and .NET applications to the Oracle Cloud. You can also deployJava EE web applications.

Subscribing to Oracle Application Container Cloud Service makes all types availablewhen you deploy your application.

Each application instance you deploy to Oracle Application Container Cloud Serviceruns in its own Docker container. A container is like a very lightweight virtual machine.Your application runs in its own isolated execution space, with its own memory, filesystem, and network access. Access to these operating system resources takes placewithout the cost of having to implement an entire virtual operating system.

1-1

You can use these key features of Oracle Application Container Cloud Service:

• A preconfigured environment for Java SE, Java EE, Node.js, PHP, Python, Ruby,Go, and .NET applications.

• Java SE advanced features such as Java Flight Recorder, Java Mission Control,advanced memory management, and ongoing and timely security updates.

• An open platform that supports all Java frameworks and containers, such asSpring, Play, Tomcat, and Jersey.

• Support for Java Virtual Machine (JVM) based languages such as JRuby. Anylanguage that uses the JVM can run on this service.

• Enterprise-grade technical support from Oracle.

• Web-based user interface and REST API.

In addition, Oracle Application Container Cloud Service is fully integrated with otherOracle Cloud platform services.

A subscription to Oracle Cloud Infrastructure Object Storage Classic is included andmust be activated before you can deploy applications to Oracle Application ContainerCloud Service.

You can develop your application on your local system, or you can use OracleDeveloper Cloud Service.

If you want to store and retrieve data, then you can subscribe to Oracle DatabaseCloud Service or Oracle MySQL Cloud Service.

For communication, you can subscribe to Oracle Messaging Cloud Service.

Typical Workflow for Developing ApplicationsComplete these tasks to create, deploy, and manage your applications in the OracleApplication Container Cloud Service.

Task Description More Information

Make sure that your new or existingapplication meets a few simple designrequirements for this service.

See DesignConsiderations.

Create and test your program locally.

If you have an application with nativelibraries, then run your build on OracleDeveloper Cloud Service, or on your ownsystem that runs Oracle Linux or acompatible distribution.

See Compiling NativeLibraries for YourApplication.

Make a standalone application with itsdependent libraries.

See Making aStandaloneApplication.

Chapter 1Typical Workflow for Developing Applications

1-2

Task Description More Information

Create one or two metadata files that specifyinformation such as:• The launch command• How many instances of your application

to deploy• How to connect to a database• Environment variables

See CreatingMetadata Files.

Create your application package. See Creating theDeployment-ReadyArchive.

Deploy your application to the service. Use the user interface,use the REST API, ordeploy from OracleDeveloper Cloud Service.

To deploy from theuser interface, see Creating anApplication in UsingOracle ApplicationContainer CloudService.

To learn about theREST API, see RESTAPI for ManagingApplications.

To deploy fromOracle DeveloperCloud Service, see Deploying anApplication to OracleApplication ContainerCloud in UsingOracle DeveloperCloud Service.

Test your application remotely.

If you have a Java application, then you canmonitor it using Java Mission Control andJava Flight Recorder.

See Java MissionControl and JavaFlight Recorder.

Chapter 1Typical Workflow for Developing Applications

1-3

Task Description More Information

Manage your application using the userinterface or the REST API.

As your application isrunning, you can:• Change the number

of instances.• Alter the amount of

memory allocated toeach instance.

• Download andreview applicationlogs.

• Upload a newversion of theapplication.

• Upload a newmanifest.jsonfile ordeployment.json file.

• Add or change thevalues ofenvironmentvariables.

• Update servicebindings.

To learn more aboutthe REST API, see REST API forManagingApplications.

To learn more aboutthe user interface,see Using theApplications Pageand Using theApplication Consolein Using OracleApplication ContainerCloud Service.

Also see Retrievingthe Application Logs.

Chapter 1Typical Workflow for Developing Applications

1-4

2Creating Your Application

When creating your application for deployment on Oracle Application Container CloudService, you must make sure it listens on the correct port, is configurable at runtime,and includes all dependent classes, including library classes.

Topics:

• Design Considerations

• Making the Application Configurable at Runtime

• Compiling Native Libraries for Your Application

Design ConsiderationsIf you are developing a new application or deploying an existing one to run on OracleApplication Container Cloud Service, keep these requirements in mind.

• Applications must be configurable at runtime. Most application types mustlisten on the port provided in the PORT environment variable. Applications canalso read user-defined environment variables and environment variables fromother services. See Making the Application Configurable at Runtime for details.

• Applications must include all dependencies. If your application requires alibrary to execute, that library must be included in the application when it isdeployed. See Making a Standalone Application.

If your application needs to maintain or share state, use Oracle Cloud InfrastructureObject Storage Classic or Oracle Database Cloud Service for storing data. To useOracle Database Cloud Service, you must configure a service binding, which you cando in the user interface or the deployment.json file. See Creating Metadata Files.

Other than these requirements, the application and the command that launches it areentirely under your control.

Making the Application Configurable at RuntimeYour application must be able to read settings from environment variables in theapplication’s container. All applications except Java EE web applications and workerapplications must read the HOSTNAME and PORT environment variables, and usethe values dynamically.

Up to three types of environment variables are available to all instances of yourapplication:

1. Your application is running inside a Docker container that has a generatedhostname and port. These are made available to the application in theHOSTNAME and PORT environment variables.

If the application is required to listen on the specified port but doesn’t, applicationcreation and deployment will fail. After deployment, the service pings theapplication on that port to determine if it’s running. The load balancer and

2-1

application ports are different. The load balancer accepts SSL traffic on port 1443,then directs requests to each application according to the port in the PORTenvironment variable.

2. If your application uses other Oracle Cloud services, service connection details(such as ports) can also be made available in environment variables.

3. You can also add your own environment variables using the user interface or thedeployment.json file. See Creating Metadata Files.

Note:

The PORT and ORA_PORT environment variables have the same value. Yourapplication can read the port using either one.

If you are programming in Java 8, you can use the Optional class to retrieve theenvironment variables without having to use if blocks to check for null values, asshown in this code snippet from the Grizzly Jersey sample application:

/** * Main class */public class Main{ // Base URI the Grizzly HTTP server will listen on public static final String BASE_URI; public static final String protocol; public static final Optional<String> host; public static final String path; public static final Optional<String> port; static{ protocol = "http://"; host = Optional.ofNullable(System.getenv("HOSTNAME")); port = Optional.ofNullable(System.getenv("PORT")); path = "myapp"; BASE_URI = protocol + host.orElse("localhost") + ":" + port.orElse("8080") + "/" + path + "/"; }

Compiling Native Libraries for Your ApplicationWhen you deploy your application, it runs in a Docker container, which is based onOracle Linux. If your application has native libraries, those libraries must be compiledon a system that runs on Oracle Linux or a compatible distribution before theapplication can be deployed.

If your Node.js application only includes Javascript .js files and no native libraries, or ifyour Java application uses no native libraries, you can skip this section.

You can build the libraries on your own system if it runs Oracle Linux or a compatibledistribution.

You can also build your libraries on Oracle Developer Cloud Service. An entitlementfor it is included with your subscription. For details about builds, see Managing Project

Chapter 2Compiling Native Libraries for Your Application

2-2

Jobs and Builds in Oracle Developer Cloud Service in Using Oracle Developer CloudService.

You do not need to compile the Oracle node-oracledb driver. It is installed globally,so it should not be included in the local node_modules folder that is included in theapplication archive. The driver is provided in the Oracle Application Container CloudService Node Docker image.

Chapter 2Compiling Native Libraries for Your Application

2-3

3Sample Applications

Use these tutorials with their sample applications to help you develop and customizeyour own applications.

The following pages in the Oracle Help Center list tutorials for various languages andtopics.

• Create Your First Applications

• Create Java SE Applications

• Create Java EE Applications

• Create Node.js Applications

• Create PHP Applications

• Create Python Applications

• Create Ruby Applications

• Create Go Applications

• Create Caching Applications

3-1

4Packaging Your Application

Once your application has been tested locally, create an archive (.zip, .tgz, .tar.gz file)that includes the application and any dependent libraries. You must also create amanifest.json file if you need to specify a launch command or other parameters.

When you have your archive, you can upload it, plus an optional deployment.jsonfile, using the user interface or the REST API.

See The Packaging Process to get started, then see other sections that apply to yourapplication type.

• The Packaging Process

• Making a Standalone Application

• Selecting the Launch Command

• Creating Metadata Files

• Creating the Deployment-Ready Archive

• Preparing a Java EE Web Application for Deployment

• Preparing a Cloud Foundry Application for Deployment

• Preparing a Clustered Application for Deployment

• Preparing a Worker Application for Deployment

The Packaging ProcessDepending on your application, you might need to perform most or all of these tasks toprepare it for deployment to Oracle Application Container Cloud Service.

• Applications must be self-contained. The application must include everything itneeds to run independently. For Java applications, this means all referencedclasses must be included. See Making a Standalone Application.

• Applications must have a single launch point. For PHP applications, a launchcommand is optional: by default a PHP application is launched from its index file.For Java EE web applications, a launch command is unnecessary. For otherapplication types, you must specify the launch command. Depending on yourapplication, this could be a Java, JavaScript, or shell command. See Selecting theLaunch Command.

• Applications that require a launch command must include a manifest.jsonfile. This file specifies information that Oracle Application Container Cloud Servicerequires to run your application properly. Optionally you can also specify additionalinformation about instance scaling, environment variables, and service bindings ina deployment.json file. See Creating Metadata Files.

• Applications must be archived in a .zip, .tgz, or tar.gz file withmanifest.json at the root if present. This ensures that Oracle ApplicationContainer Cloud Service can find the manifest.json file. See Creating the

4-1

Deployment-Ready Archive. You don’t need to include a Java EE web applicationin a .zip, .tgz, or .tar.gz file unless you need to set values in the manifest.jsonfile, which is optional.

Some application types have additional requirements:

• Preparing a Java EE Web Application for Deployment

• Preparing a Cloud Foundry Application for Deployment

• Preparing a Clustered Application for Deployment

• Preparing a Worker Application for Deployment

Making a Standalone ApplicationOnce you have developed your application, you need to decide how to include orreference any dependent libraries. For a Java application, you can do this by creatingan uber JAR file or by using the classpath. Remember that the command used tolaunch your application is up to you.

If you create a JAR file containing your application, by default only the class filesgenerated from the source files are included in the JAR. If your application depends onlibrary classes, this does not produce a standalone application file that can be runanywhere.

Each application package must include or reference any dependent libraries when it isdeployed. You can accomplish this in one of two ways:

• Create an uber JAR. When creating your application, you include all dependentlibraries in the JAR with the application. If you are using Maven, you can use theMaven build tool and either the assembly or shade plugin to copy the requiredlibraries into the JAR file. Instructions for creating an uber JAR with the assembly

plugin are in this tutorial: Creating a Basic REST Web Service using Grizzly,Jersey, and Maven.

• Use the classpath. All dependent libraries are included in separate JAR files, butthe path to each file is included in the -classpath option on the command line. Ifyou have a lot of libraries included in your application, the classpath can get long,but you can put the command line into a bash shell script and execute that ifdesired. If you are using Maven, you can use the appassembler plugin to write thebash script.

Selecting the Launch CommandYou have total control over your launch command. You can launch directly by invokingjava... or node..., or use a shell script. The application is executed in a Linuxcontainer, so most of the rules that apply to running a command in Linux apply.

A PHP application typically doesn’t need a launch command. Unless another file isspecified in the application URL, the index file opens first, whether the extensionis .htm, .html, or .php. If you use a launch command because you need to run ascript before starting your application, the last command in the script must be apache2–run. PHP is dependent on the Apache HTTP server and Oracle Application ContainerCloud Service doesn’t start it automatically if a launch command is present. For a JavaEE web application, a launch command, if present, is ignored.

Chapter 4Making a Standalone Application

4-2

For other application types, you must specify the launch command in themanifest.json metadata file that you include with the application. See CreatingMetadata Files.

If you are using a JVM-based language, the launch command can start the applicationwith any number of JVM switches.

Java Launch Command Example Assumptions

The examples that follow are based on the following assumptions:

• The home directory for the application is stored in the $APP_HOME environmentvariable.

• The application execution code is stored in a JAR file named app.jar, which islocated in $APP_HOME.

• All required Java libraries are stored in the lib directory. The lib directory isincluded as part of the final archive as a subdirectory from the archive rootdirectory.

• The lib directory contains the following jar libraries: web.jar, rest.jar,media.jar.

If the lib directory is not included in the application JAR file, you must specify theclasspath so the JVM can find all the classes necessary to run the application.

Executing the Application and Setting the Classpath in the Manifest.mf File

Given these assumptions, the following java command could launch the application:

java -jar app.jar

The JAR must include a Manifest.mf file with Main-Class set to the main class andClass-Path set to lib/web.jar lib/rest.jar lib/media.jar.

Executing the Application and Setting the Classpath Using the -cp Option

You can use the -classpath or -cp option to specify the location of the main applicationJAR and the dependent JAR files. This option is incompatible with the –jar option, soyou execute the main class directly. For example:

java -cp $APP_HOME/app.jar:$APP_HOME/lib/* com.example.Main

Note that on Linux, the path separator is a colon, not a semicolon as on Windows.

Executing the Application in an Uber JAR

If the application is packaged as an uber JAR called uber-app.jar, with all thedependencies available in the JAR, an external classpath isn’t needed. The uber JARmust include a Manifest.mf with the main class. To run the application:

java -jar uber-app.jar

Executing the Application with a Shell Script

As an alternative, you can execute your application using a shell script. The commandline for execution would be something like this:

sh ./applicationScript.sh

Chapter 4Selecting the Launch Command

4-3

Creating Metadata FilesYou can specify deployment information, such as the launch command, the number ofapplication instances to create, and service bindings, in one or two metadata files thatyou upload with your application.

When you upload your application to Oracle Application Container Cloud Service usingthe user interface, you must include a file called manifest.json if your applicationrequires a launch command. This file can be included at the root of the archive orspecified separately.

The other file, deployment.json, is optional and is not included in the archive. Youcan specify the values in this file via the user interface, or you can upload the file usingthe REST API.

The manifest.json File

The manifest.json file specifies how to launch your application. Optionally, you caninclude the runtime version and other parameters.

manifest.json Syntax

Syntax

• runtime

– majorVersion – (Optional) Major version of the runtime environment. Eachlanguage has its own numbering system.

* For Java SE, use 7, 8, or 9.

* For Java EE, use 7.

* For Node, use 0.10 , 0.12, 4, 6, or 8.

* For PHP, use 5.6, 7.0, or 7.1.

* For Python, use 2.7.13, 2.7.14, 3.6.0, 3.6.1, 3.6.2, or 3.6.3.

* For Ruby, use 2.3.4, 2.3.5, 2.4.1, or 2.4.2.

* For Go, use 1.7.6, 1.8.3, 1.8.4, or 1.8.5.

* For .NET, use 1.1.2–runtime or 2.0.0–runtime.

• type – (Optional) Determines whether an application is public or private:

– web (the default) – Specifies a public application, which you can access using apublic URL, the public REST API, or the command-line interface.

– worker – Specifies a worker application, which is private and runs in thebackground. The isClustered parameter should be set to true in some cases.See Preparing a Worker Application for Deployment.

• command – (Required except for Java EE and PHP) Launch command toexecute after the application has been uploaded.

Most PHP applications don’t need a launch command. Unless another file isspecified in the application URL, the index file opens first, whether the extensionis .htm, .html, or .php. See Selecting the Launch Command.

For a Java EE web application, the launch command, if present, is ignored.

Chapter 4Creating Metadata Files

4-4

• startupTime – (Optional) Maximum time in seconds to wait for the application tostart. Allowed values are between 10 and 600. The default is 30. If the applicationdoesn’t start in the time specified, the application is deemed to have failed to startand is terminated. For example, if your application takes two minutes to start, setstartupTime to at least 120.

• shutdownTime – (Optional) Maximum time in seconds to wait for the applicationto stop. Allowed values are between 0 and 600. The default is 0. This allows theapplication to close connections and free up resources gracefully. For example, ifyour application takes two minutes to shut down, set shutdownTime to at least120.

• release – (Optional)

– build – User-specified value of build.

– commit – User-specified value of commit.

– version – User-specified application version.

• notes – (Optional) Comments.

• mode – (Optional) Restart mode for application instances when the application isrestarted. The only allowed option is rolling for a rolling restart. Omit thisparameter to be prompted for a rolling or concurrent restart. See Stopping,Starting, and Restarting an Application in Using Oracle Application ContainerCloud Service.

• isClustered – (Optional) Must be set to true for application instances to act as acluster, with failover capability. See Preparing a Clustered Application forDeployment.

Example 4-1 Sample manifest.json for a Java application

{ "runtime": { "majorVersion": "7" }, "type": "web", "command": "java -jar myapp.jar", "startupTime": "120", "release": { "build": "150520.1154", "commit": "d8c2596364d9584050461", "version": "15.1.0" }, "notes": "notes related to release", "mode": "rolling"}

Example 4-2 Sample manifest.json for a Node application

{ "runtime":{ "majorVersion":"0.12"}, "command": "node server.js", "mode": "rolling"}

Chapter 4Creating Metadata Files

4-5

Example 4-3 Sample manifest.json for a PHP application

{ "runtime":{ "majorVersion":"5.6"}, "command": "sh app.sh", "notes": "This PHP app is launched from a script", "mode": "rolling"}

Example 4-4 Sample manifest.json for a Python application

{ "runtime":{ "majorVersion":"3.6.0"}, "command": "python app.py", "mode": "rolling"}

Example 4-5 Sample manifest.json for a Ruby application

{ "runtime":{ "majorVersion":"2.4.1"}, "command": "ruby app.rb", "mode": "rolling"}

Example 4-6 Sample manifest.json for a Go application

{ "runtime":{ "majorVersion":"1.8.3"}, "command": "go run app.go", "mode": "rolling"}

The deployment.json File

This file is optional.

The deployment.json file specifies how much memory to allocate to theapplication, how many application instances to create initially, additional environmentvariables, and service bindings to other Oracle Cloud services. You can specify thesesame options from the user interface, or you can upload this file using the REST API.If no values are specified or the file is omitted, memory and instance defaults are used.

When a service binding is created, its environment variables are automatically created.For example, for Oracle Database Cloud Service, these variables have namesbeginning with DBAAS_. See Configuring Environment Variables in Using OracleApplication Container Cloud Service.

deployment.json Syntax

• memory – The amount of memory in gigabytes made available to the application.Values range from 1G to 20G. The default is 2G.

Chapter 4Creating Metadata Files

4-6

• instances – Number of application instances. The default is 2. The maximum is64.

• notes – Free-form comment field. It can be used, for example, to describe thedeployment plan.

• environment – Environment variables used by the application. This element cancontain any number of name-value pairs.

– name – Environment variable name.

– value – Environment variable value.

• java_system_properties – Java EE system properties used by the application.This element can contain any number of name-value pairs.

– name – Property name.

– value – Property value.

• services – Service bindings for connections to other Oracle Cloud services. Thiselement can contain more than one block of sub-elements. Each block specifiesone service binding.

– identifier – User-specified identifier.

– type – Type of the service: JAAS for Oracle Java Cloud Service, DBAAS forOracle Database Cloud Service, MYSQLCS for MySQL Cloud Service, OEHCS foran Oracle Event Hub Cloud Service topic, OEHPCS for an Oracle Event HubCloud Service cluster, DHCS for Oracle Data Hub Cloud Service, or caching for acache.

– name – Name of the service, the name of an existing Oracle Java CloudService instance, Oracle Database Cloud Service database, MySQL CloudService database, Oracle Event Hub Cloud Service topic or cluster, OracleData Hub Cloud Service instance, or cache name.

– username – Username used to access the service.

– password – Password for the username.

Note:

The username and password are not automatically used to authenticateagainst the target service. The values are placed in theSERVICE_USER_NAME and SERVICE_USER_PASSWORD environmentvariables, which your application can access. If the target service requiresauthentication, your application must handle it. If the target service doesn’trequire authentication, you can’t omit the username and password from theservices element, but you can specify any values.

Chapter 4Creating Metadata Files

4-7

Note:

If you download a deployment.json file from a deployed application that hasa service binding, you see an additional id element under services. The valueof this element is system-generated. For a new application, do not upload adeployment.json file that includes this element. For an existing application,do not change the value of this element.

Example 4-7 deployment.json Example

{ "memory": "2G", "instances": "2", "environment": { "NO_OF_CONNECTIONS":"25", "TWITTER_ID":"JAVA" }, "services": [{ "identifier": "ProdService", "type": "JAAS", "name": "Jaas Service", "username": "username", "password": "password" }, { "identifier": "DBService", "type": "DBAAS", "name": "MyDB", "username": "username", "password": "password" }]}

Creating the Deployment-Ready ArchiveFinally, create an archive that includes your application and its manifest.json file, ifpresent, at the root. Use a zip or tar utility.

You don’t need to include a Java EE web application in a .zip, .tgz, or .tar.gz fileunless you need to set values in the manifest.json file, which is optional for thisapplication type.

Do not include deployment.json in your compressed archive.

For example, create an archive called myapp.zip using zip.

zip myapp.zip manifest.json myapp.jar

Here is an example using tar.

tar cvfz myapp.tgz manifest.json myapp.jar

Deploying the Archive

Now your application is ready for deployment. You can deploy your application usingthe web user interface, using the REST API, or from Oracle Developer Cloud Service.

Chapter 4Creating the Deployment-Ready Archive

4-8

To learn more about how to deploy an application using the web user interface, see Creating an Application in Using Oracle Application Container Cloud Service.

To learn about how to deploy an application from Oracle Developer Cloud Service, see Deploying an Application to Oracle Application Container Cloud in Using OracleDeveloper Cloud Service.

Deploying the Archive Using the REST API

To deploy an application using the REST API, first create your archive (a zip file plus,optionally, a non-zipped manifest file in the same directory, or a .war file for a JavaEE application) and place it in your Oracle Cloud Infrastructure Object Storage Classicaccount.

This example shows how to deploy a Java application called MyFirstApp by submittinga POST request using cURL. The archiveURL points to the location of your archivewithin your storage service account.

curl -X POST -u joe@example.com:password \-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \-H "Content-Type: multipart/form-data" -F "name=MyFirstApp" \-F "runtime=java" -F "subscription=Monthly" \-F "manifest=@manifest.json" -F "deployment=@deployment.json" \-F "archiveURL=mydomain/binaries/myapp.zip" \-F "notes=notes for deployment" \https://apaas.oraclecloud.com/paas/service/apaas/api/v1.1/apps/ExampleIdentityDomain

As you can see from the example, you have the option of supplying manifest.jsonseparately or within the zipped archive (or both). If you specify a manifest.json onthe command line, that file overrides a manifest.json in the zipped archive.

More generally, any option on the command line (such as, subscription or name) takesprecedence over the same option in a metadata file, if there is a difference.

To learn more about the REST API, see REST API for Managing Applications.

Preparing a Java EE Web Application for DeploymentYou can deploy a Java EE web application to Oracle Application Container CloudService with minimal changes to how it’s packaged.

Your Java EE web application must meet some standard Oracle Application ContainerCloud Service requirements, while others are optional or not applicable.

• Only Java EE version 7 is supported.

• Your web application doesn’t need to read the APP_HOME and PORTenvironment variables.

• Your web application doesn’t use a launch command.

• Your web application must include all dependent classes that are not included inWebLogic Server.

• A manifest.json file is optional. You can deploy either a single .war file ora .zip, .tar, or .tar.gz file with an optional manifest.json file and asingle .war file at the root. The isClustered parameter is not supported.

• If your web application requires a service binding to a DBCS or MySQLCSdatabase, you must specify it in a deployment.json file. A WebLogic data

Chapter 4Preparing a Java EE Web Application for Deployment

4-9

source is automatically created with the default name jdbc/service-binding-nameDS. You can specify database driver and data source parameters in this file ifnecessary. Names of data source properties align with WebLogic data sourceMBean properties.

• You can define any needed environment variables and system properties in adeployment.json file.

• Your web application can interact with a cache using the Java API or the RESTAPI.

For details about the manifest.json and deployment.json files, see CreatingMetadata Files.

After deployment, your web application has these features:

• Your web application is deployed to WebLogic Server on the back end.

• You can scale memory and instances just as you can with any application.

• You can stop, start, and restart just as you can with any application.

Most standard web application features are supported, with a few exceptions.

• XA and RAC integration are not supported.

• ADF is not supported.

• Although a weblogic.xml file isn’t required, it is used if present.

Deploying the Archive Using the Command-Line Interface

To deploy your web application using the command-line interface, use the accs pushcommand. See accs push in PaaS Service Manager Command Line InterfaceReference.

If your web application is especially large, you can create your archive and place it inyour Oracle Cloud Infrastructure Object Storage Classic account, then deploy it fromthere using accs push.

Deploying the Archive Using the REST API

To deploy your web application using the REST API, first create your archive andplace it in your Oracle Cloud Infrastructure Object Storage Classic account.

This example shows how to deploy a Java application called MyEEApp by submittinga POST request using cURL. The archiveURL points to the location of your archivewithin your storage service account.

curl -X POST -u joe@example.com:password \-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \-H "Content-Type: multipart/form-data" -F "name=MyEEApp" \-F "runtime=javaee" -F "subscription=Monthly" \-F "deployment=@deployment.json" \-F "archiveURL=mydomain/binaries/myeeapp.zip" \-F "notes=notes for deployment" \https://apaas.oraclecloud.com/paas/service/apaas/api/v1.1/apps/ExampleIdentityDomain

Any option on the command line (such as subscription or name) takes precedenceover the same option in a metadata file, if there is a difference.

For more information about the REST API, see REST API for Oracle ApplicationContainer Cloud Service.

Chapter 4Preparing a Java EE Web Application for Deployment

4-10

Preparing a Cloud Foundry Application for DeploymentYou can deploy a Cloud Foundry application to Oracle Application Container CloudService with minimal changes to how it’s packaged, using your existingmanifest.yml file.

You can deploy your Cloud Foundry application to Oracle Application Container CloudService as is if it meets these conditions:

• The manifest.yml file contains information for only one application.

• The manifest.yml file contains no service bindings to databases.

• The manifest.yml file is located in the root directory of the application ZIP file tobe uploaded.

• All dependencies are included in a single file, either the application main class or aJAR file. Unlike Cloud Foundry, Oracle Application Container Cloud Servicedoesn’t download dependencies.

If your application requires a service binding to a database, you must specify it in adeployment.json file. See Creating Metadata Files. All other conditions arerequirements.

Oracle Application Container Cloud Service interprets the manifest.yml file asfollows:

• Supported manifest.yml attributes are name, memory, instances, path, env, andtimeout.

• The launch command is automatically generated based on the path attribute.

• The memory value is rounded up to the nearest gigabyte.

• Service bindings and unsupported options are ignored.

• If present, manifest.json and deployment.json files override equivalentoptions in the manifest.yml file.

Deploying the Archive Using the Command-Line Interface

To deploy your Cloud Foundry application using the command-line interface, createyour archive and place it in your Oracle Cloud Infrastructure Object Storage Classicaccount.

Then use the accs push command. See accs push in PSM CLI Reference.

Deploying the Archive Using the REST API

To deploy your Cloud Foundry application using the REST API, create your archiveand place it in your Oracle Cloud Infrastructure Object Storage Classic account.

This example shows how to deploy a Java application called MyCFApp by submittinga POST request using cURL. The archiveURL points to the location of your archivewithin your storage service account.

Note that the REST URL contains the cliapps parameter rather than the usual appsparameter.

Chapter 4Preparing a Cloud Foundry Application for Deployment

4-11

curl -X POST -u joe@example.com:password \-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \-H "Content-Type: multipart/form-data" -F "name=MyCFApp" \-F "runtime=java" -F "subscription=Monthly" \-F "deployment=@deployment.json" \-F "archiveURL=mydomain/binaries/mycfapp.zip" \-F "notes=notes for deployment" \https://apaas.oraclecloud.com/paas/service/apaas/api/v1.1/cliapps/ExampleIdentityDomain

Any option on the command line (such as subscription or name) takes precedenceover the same option in a metadata file, if there is a difference.

To learn more about the REST API, see REST API for Managing Applications.

Preparing a Clustered Application for DeploymentYou can deploy a clustered application to Oracle Application Container Cloud Servicewith standard scaling of instances. The instances in a clustered application act as asingle unit in response to client requests. Each instance replicates and thereby sharessession data.

Benefits of clustered applications include:

• Performance — Since more than one instance is available to perform a task or unitof work, response time is often faster.

• Scaling — A clustered application can be scaled out with more and moreinstances to handle more and more work.

• Load Balancing — When a request comes into a clustered application, the loadbalancer passes it to one of the instances. Load balancers can use anything fromcomplex algorithms to a simple round robin approach to route traffic. OracleApplication Container Cloud Service uses Oracle Traffic Director for loadbalancing.

• High Availability — Highly available systems are designed with redundancy thateliminates a single point of failure. In a clustered application, if one instance fails,the other instances continue running and take over the request processing that thefailed instance was handling. From outside the application, there appears to be nochange in the way it operates.

Setting the Mulitcast IP Address and Port

Your clustered instances must be able to discover each other in order to share sessiondata. One way they can do this is to use multicasting.

To use multicasting, you must select the multicast IP address and port that yourclustered application will use. For example, the default values used by Apache Tomcatare 228.0.0.4 and 45564 respectively. Valid multicast IP addresses are described atthe IPv4 Multicast Address Space Registry.

It is very important that the multicast IP address and port combination be unique inyour identity domain. If different clusters use the same combination, they behave like afused cluster, causing problems for all applications involved.

To avoid having to set the multicast IP address and port manually in each applicationinstance, set them as environment variables in the deployment.json file and pass

Chapter 4Preparing a Clustered Application for Deployment

4-12

them to the application instances in the launch command. This is recommended as abest practice.

Like most Oracle Application Container Cloud Service applications, a clusteredapplication must read the standard PORT environment variable, which is different fromthe multicast port.

For example, Tomcat stores the multicast IP address, multicast port, and standardPORT in the server.xml file. You can create a template of this file and use thelaunch command to copy this file for each instance and substitute environmentvariable values in each copy.

Copy the conf/server.xml file and create a new file named conf/server.template.xml. Edit the <Service name="Catalina"> section to reference thestandard PORT environment variable:

<Connector port="__PORT__" protocol="HTTP/1.1" connectionTimeout="20000" ... >

Edit the <Engine name="Catalina" ... > subsection to reference the multicast IPaddress and port:

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"> <Channel className="org.apache.catalina.tribes.group.GroupChannel"> <Membership className="org.apache.catalina.tribes.membership.McastService" address="__MIP__" port="__MPORT__" frequency="500" dropTime="3000"/> </Channel></Cluster>

Use a sed command in the launch script that replaces the multicast address and portand the standard PORT with environment variables:

sed "s/__PORT__/${PORT}/g; s/__MIP__/${MIP}/g; s/__MPORT__/${MPORT}/g" conf/server.template.xml > conf/server.xml

Note:

For local testing, you can omit the sed command from the launch script and usethe actual PORT, multicast IP, and multicast port values in the application.

For a full tutorial of how to create an example clustered application that uses

multicasting based on Tomcat, see Creating a Tomcat Cluster with TCP SessionReplication.

Configuring a Web Application

For failover to work, a web application must have <distributable/> set in its web.xmlfile.

You can download a useful sample application based on Tomcat at clusterjsp.zip.

Chapter 4Preparing a Clustered Application for Deployment

4-13

Configuring the Metadata Files and Creating the Archive

Set the following parameters in the manifest.json file using the launch commandyou need:

{ "runtime": { "majorVersion": "8" }, "command": "./start.sh", "isClustered" : "true"}

Set the following parameters in the deployment.json file using the values youneed:

{ "memory": "1G", "instances": "2", "environment": { "MIP":"228.0.0.4", "MPORT":"45565" }}

For details about other possible parameters in the manifest.json anddeployment.json files, see Creating Metadata Files.

You can include the manifest.json file at the root of the application archive, or youcan reference it separately at deployment time. Do not include thedeployment.json file, which must be referenced separately.

Deploying the Archive Using the Command-Line Interface

To deploy your cluster using the command-line interface, create your archive andplace it in your Oracle Cloud Infrastructure Object Storage Classic account.

Then use the accs push command. See accs push in PSM CLI Reference.

Deploying the Archive Using the REST API

To deploy your cluster using the REST API, create your archive and place it in yourOracle Cloud Infrastructure Object Storage Classic account.

This example shows how to deploy a MyCluster by submitting a POST request usingcURL. The archiveURL points to the location of your archive within your storageservice account.

curl -X POST -u joe@example.com:password \-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \-H "Content-Type: multipart/form-data" -F "name=MyCluster" \-F "runtime=java" -F "subscription=Monthly" \-F "deployment=@deployment.json" \-F "archiveURL=mydomain/binaries/mycluster.zip" \-F "notes=notes for deployment" \https://apaas.oraclecloud.com/paas/service/apaas/api/v1.1/apps/ExampleIdentityDomain

Any option on the command line (such as subscription or name) takes precedenceover the same option in a metadata file, if there is a difference.

Chapter 4Preparing a Clustered Application for Deployment

4-14

To learn more about the REST API, see REST API for Managing Applications.

Preparing a Worker Application for DeploymentYou can deploy a worker application to Oracle Application Container Cloud Service. Aworker application is accessible over a private overlay network to the otherapplications deployed within your identity domain and is not accessible to end users.

You can’t access a worker application using a public URL, the public REST API, or thePaaS Service Manager command-line interface. It doesn’t need to read the PORTenvironment variable, although it can do so. Like a public application, it can useenvironment variables and service bindings, and it can be scaled and monitored.

To specify a worker application, set the following parameters in the manifest.jsonfile:

• "type":"worker" – (Required) Specifies a worker application.

• "isClustered":"true" – (Optional) Specifies that the application is clustered, whichis often necessary for a worker application to communicate with a publicapplication.

You can’t change a worker application to a public application by redeploying it. Youmust delete the application, make the change, then deploy it as a new application.

A private application communicates with other applications asynchronously, bygenerating or listening to messages. These messages can be to or from a publish/subscribe service such as Oracle Event Hub Cloud Service. Direct point-to-pointcommunication is not supported.

Deploying the Archive Using the Command-Line Interface

To deploy your private application using the command-line interface, create yourarchive and place it in your Oracle Cloud Infrastructure Object Storage Classicaccount.

Then use the accs push command. See accs push in PSM CLI Reference.

Deploying the Archive Using the REST API

To deploy your private application using the REST API, create your archive and placeit in your Oracle Cloud Infrastructure Object Storage Classic account.

This example shows how to deploy a Java application called MyPrivateApp bysubmitting a POST request using cURL. The archiveURL points to the location ofyour archive within your storage service account.

curl -X POST -u joe@example.com:password \-H "X-ID-TENANT-NAME:ExampleIdentityDomain" \-H "Content-Type: multipart/form-data" -F "name=MyPrivateApp" \-F "runtime=java" -F "subscription=Monthly" \-F "deployment=@deployment.json" \-F "archiveURL=mydomain/binaries/myprivapp.zip" \-F "notes=notes for deployment" \https://apaas.oraclecloud.com/paas/service/apaas/api/v1.1/apps/ExampleIdentityDomain

Any option on the command line (such as subscription or name) takes precedenceover the same option in a metadata file, if there is a difference.

Chapter 4Preparing a Worker Application for Deployment

4-15

To learn more about the REST API, see REST API for Managing Applications.

Chapter 4Preparing a Worker Application for Deployment

4-16

5Monitoring Your Application

You can monitor your Java applications using Java Flight Recorder and Java MissionControl. Additionally, applications can write to log files that are stored on Oracle CloudInfrastructure Object Storage Classic.

Topics:

• Java Mission Control and Java Flight Recorder

• Retrieving the Application Logs

Java Mission Control and Java Flight RecorderJava Flight Recorder and Java Mission Control are included in your subscription.

Java Mission Control (JMC) enables you to monitor and manage Java applicationswithout introducing the performance overhead normally associated with these types oftools. It uses data collected for normal adaptive dynamic optimization of the JavaVirtual Machine (JVM). Besides minimizing the performance overhead, this approacheliminates the problem of the observer effect, which occurs when monitoring tools alterthe execution characteristics of the system.

Java Flight Recorder (JFR) collects and saves detailed performance characteristics forhistoric analysis and profiling. When used as a plug-in for the JMC client, it presentsdiagnostic information in logically grouped tables, charts, and dials.

You can record 60 seconds of information at a time on each application. If you havemultiple instances, each instance generates a recording. Then you can examine thedata retrieved using Java Mission Control, and make necessary adjustments based onthat data.

See the Java Mission Control User’s Guide and Java Flight Recorder Runtime Guidein the Java Components Documentation.

Retrieving the Application LogsYou may want to check your application logs to monitor the application or troubleshoota problem. Information that your application sends to stdout or stderr is captured inthe logs. The logs are stored on Oracle Cloud Infrastructure Object Storage Classic.You can download the logs using the user interface or the REST API.

If your application was successfully deployed, you can view the log from the userinterface. If prompted for credentials, use your storage service username andpassword.

If application deployment failed, you can view the log by retrieving it from Oracle CloudInfrastructure Object Storage Classic using the REST API. The log path is available inthe application creation and failures history on the Applications page in the userinterface.

5-1

Using the REST API to Retrieve a Log

To download the log for an application from Oracle Cloud Infrastructure ObjectStorage Classic, use the following command as a reference. You will need the cURLutility and the storage service information that you received when you subscribed tothe service.

First you will need an authentication token. Here’s an example of a cURL command forrequesting an authentication token:

curl -v -X GET \ -H "X-Storage-User: myService-myIdentityDomain:myUsername" \ -H "X-Storage-Pass: myPassword" \ https://storage.us2.oraclecloud.com/auth/v1.0

Once you have the token, you can request the log, as in this example:

curl -v -X GET \ -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \ -o destinationFileName \ https://storage.us2.oraclecloud.com/v1/Storage-myIdentityDomain/myContainer/myApplicationLog

To learn more about the Oracle Cloud Infrastructure Object Storage Classic RESTAPI, see REST API for Standard Storage in Oracle Storage Cloud Service.

Chapter 5Retrieving the Application Logs

5-2

6Troubleshooting Oracle ApplicationContainer Cloud Service

This section describes common problems that you might encounter when using OracleApplication Container Cloud Service and explains how to solve them.

Topics

• Why won't my application deploy?

• My application starts to deploy, but then it disappears from the application list.

• My application deploys but doesn't run.

• My clustered application deploys but doesn't connect.

• My REST request fails with a 403 error.

Why won't my application deploy?

Your application is of a type that requires a requires a launch command. You uploadyour application archive in the Create Application dialog but nothing happens. Thefollowing error message flashes on the screen:

Unsuccessful upload, because the manifest file named manifest.json could not be found.

Here are some common causes of this problem:

• The manifest.json file is actually missing. It wasn’t at the root of the archive orspecified during deployment.

• There is a typo in the name of the manifest.json file.

• The manifest.json file is not located in the root directory of the archive. This isthe most common reason for this problem.

Typically, when you zip something to share, you put all the files in a subdirectoryand then zip the subdirectory. However, this results in a root directory thatcontains the subdirectory. Oracle Application Container Cloud Service will not beable to find the manifest file and therefore will be unable to deploy yourapplication. See Creating the Deployment-Ready Archive.

My application starts to deploy, but then it disappears from the application list.

You upload your application to Oracle Application Container Cloud Service and itstarts to deploy. You go for a cup of coffee and when you return, the application hasdisappeared.

You application failed to deploy. To find out why, do the following:

1. Go to the Applications Page. See Using the Applications Page in Using OracleApplication Container Cloud Service.

2. Click the Application Creation and Deletion History.

6-1

3. Find the application you tried to deploy in the history.

4. Click the Details link or download the server logs.

Either of these options shows you the error message encountered duringdeployment. Downloading the log files provides the most information.

Here are the most common causes of this problem:

• Your launch command is incorrect, possibly due to a typo. See Selecting theLaunch Command.

• Your application archive is missing a dependent library. Make sure yourapplication can launch stand-alone, separate from your build environment. See Making a Standalone Application.

My application deploys but doesn't run.

Your application runs locally and has deployed successfully, but when you try to test itin Oracle Application Container Cloud Service, you get no response.

The most common cause of this problem is that your application is of a type that isrequired to read the PORT environment variable provided by the Oracle ApplicationContainer Cloud Service container but doesn’t read them. This results in yourapplication listening on the wrong port, unavailable for testing. Oracle ApplicationContainer Cloud Service typically listens on SSL port 443 (HTTPS). See Making theApplication Configurable at Runtime.

My clustered application deploys but doesn't connect.

Your clustered application deploys successfully, but it can't connect to other cluster-enabled applications.

When you look at the log, you may see a java.net.UnknownHostException error.

The most common cause of this problem is that your application doesn’t haveisClustered set to true in the manifest.json file. The isClustered parameter cannotbe reset once an application is deployed, so you must delete the application, set theisClustered parameter in the manifest.json file to true, and deploy the applicationas if it were new.

For descriptions of all the parameters in the manifest.json file, see CreatingMetadata Files.

My REST request fails with a 403 error.

You submit an Oracle Application Container Cloud Service REST API request and geta 403 Forbidden response.

The most common cause of this error is forgetting to include the username andpassword in the request. In a cURL command, you specify these using the -u or --useroption. See the Use cURL section in REST API for Managing Applications.

Chapter 6

6-2