Oracle by Example brandingDeploying an Application to Oracle Java Cloud Service by Using Maven

section 0Before You Begin

This tutorial shows you how to deploy a WAR file to Oracle Java Cloud Service using the Maven build tool. You would need about 45 minutes to complete this tutorial.

Last Updated

December 2016

Note that Oracle develops cloud services in an agile manner and makes rapid changes to meet our users' needs. This tutorial may not reflect all of the changes since the last update to the cloud service. For the latest information, see:

Background

With Oracle Java Cloud Service, you can quickly create and configure an Oracle WebLogic Server domain and set up your Java Platform Enterprise Edition (Java EE) application environment without worrying about infrastructure or platform details.

WAR files can be deployed using the Weblogic Administration Console, but if your application is part of an automated build/deployment process, or you do not wish to run the Administration Console, then you can use a tool such as Maven to handle the build and deployment for you.

What Do You Need?

Before starting this tutorial:

  • An Oracle Java Cloud Service instance, with access to the administration consoles enabled.
  • Administrator credentials for the WebLogic Server Administration Console of your Oracle Java Cloud Service instance. You specified the credentials when you created your Oracle Java Cloud Service instance.
  • A Java web application. For this tutorial, download the sample benefits.war application.
  • A recent Oracle® Java Development Kit™ (Version 1.8+) installed and running on your local machine.
  • An installation of the Weblogic Server (Version 12.2.1.x) running on your local machine. You can find instructions to install WebLogic Server on your local machine here: Oracle WebLogic Server 12c (12.2.1): Installing WebLogic Server Using the Quick Installer

    Note: You are not required to run WebLogic Server locally for the Maven deployment, but you will require the WebLogic Maven Deployment plugin that comes as part of the installation.

section 1Create a New Channel

You must configure your Oracle Java Cloud Service instance to accept instructions from Maven. In your WebLogic Server Administration console, create a new channel for communication between the administration server and Maven running on your local machine.

  1. In your Oracle Java Cloud Service console, open the WebLogic Server console for your instance.
    Accessing the Weblogic console
    Description of this image
  2. Enter your password and then navigate to the Server page. From the list of servers, click the administration server.
    Page listing weblogic servers
    Description of this image
  3. On the Settings page for your administration server, make a note of the server's Listen Address as you'll need it later. Then click the Protocols tab.
    Server settings page
    Description of this image
  4. Click the Lock & Edit button to prevent anyone else from making changes to the server configuration from another terminal while you are editing the same configuration on this one.

    Select the Enable Tunneling checkbox.

    Click the Channels tab.

    Selecting the channels tab
    Description of this image
  5. Click the New button to initiate the creation of a new channel.
    Adding new channel
    Description of this image
  6. Give your new channel a name. In this example we have used maven_channel.

    Next, select t3 from the Protocol dropdown. Click Next to continue to the next screen.

    Create a new channel
    Description of this image
  7. Now define the addresses and ports that the channel will communicate through.
    Parameter Description
    Listen address This is the fully qualified host name of your server, which you made a note of earlier.

    In this example the Listen address is wcp-wls-1.fmwcert.ucfc2z3a.usdv1.oraclecloud.com
    Listen port The port address that the server will listen on. In this example, it is 7005.
    External Listen Address This is the address that Maven will use to communicate with on this channel.
    External Listen Port This is the port that associated with the External Listen Address. In this example, it is 7005.

    When you have set the parameters, click Next.

    Setting network addresses
    Description of this image
  8. Enable the protocols for the connection:
    • Select the Enabled checkbox.
    • Select the Tunneling Enabled checkbox.
    • Select the HTTP Enabled for this Protocol checkbox.

    Now click the Finish button to return to the channels list where you will see your newly created channel.

  9. Now click Activate Changes to unlock the server.
    Activate the changes to the server configuration
    Description of this image

section 2Create a New Access Rule

You must now create an access rule attached to your Oracle Java Cloud Service instance so that requests from your local Maven program can be dispatched through to WebLogic Server.

  1. Return to your Oracle Java Cloud Service console. Select Access Rules from the main menu of your instance.
    Access Rules menu item
    Description of this image

  2. On the Access Rules page, click Create Rule.

    Access Rules List
    Description of this image

  3. Fill in the details.

    Parameter Description
    Rule Name The access rule must have a unique name. In this example, it is called test_maven.
    Description You can supply an optional description for your new rule.
    Source This is the external source where the requests originate. This should be set to PUBLIC-INTERNET.
    Destination Where the requests are routed. This should set to WLS_ADMIN_SERVER.
    Destination Port The port address where the requests are routed. This example uses port 7005.
    Protocol This should be set to TCP.

    Create new access rule details
    Description of this image

    Click Create when you've finished.

section 3Install Maven

First, download a Maven distribution from the Apache website to your local machine and install it. There are a number of environment variables that you will need to set up to ensure the installation can find your Java Development Kit and a directory location to store artifacts required during the build/deployment process.

  1. Download the version 3.3.9 of the Maven distribution zip file from the location http://maven.apache.org/download.cgi
  2. Unzip the archive file which contains a directory apache-maven-3.3.9. The directory should be copied to a suitable location on your local machine. For example, on a Windows-based machine, you can copy the directory to the root of your C:\ drive. On a Linux machine, you could copy the installation directory to your /usr/bin folder.

section 4Configure Your Local Environment

To run, Maven needs to know where to find your local JDK (Java Development Kit) and where to store its information repository. These locations (and a couple of others) are configured by setting environment variables.

  1. If you have a JDK running on your local machine, then the JAVA_HOME environment variable should already exist.

    On Windows, open a command shell and enter the following command:

    echo %JAVA_HOME%

    If you are running under Linux/Unix, then use the terminal shell command:

    echo $JAVA_HOME

    The echo command should come back with the location of your JDK installation directory. If it does not, then you will have to set them to point to your JDK location.

    On Windows:

    set JAVA_HOME=location_of_JDK

    On Linux/Unix:

    set JAVA_HOME=location_of_JDK
export JAVA_HOME
  2. You will also need to set the path variables so that the terminal/command shell can find the Maven executable files. Append the new location to the existing path, rather than overwrite the path completely.

    On Windows, the command would look like this, given that the executables live inside the bin directory:

    set PATH=%PATH%;c:\apache-maven-3.3.9\bin

    The command is very similar on Linux/Unix, except that you also need to export the setting to make it available to the environment.

    set PATH=$PATH:/user/bin/apache-maven-3.3.9/bin
export PATH
  3. You will also need to point the MAVEN_HOME variable to the directory of the Maven installation.

    On Windows: 

    set MAVEN_HOME=c:\apache-maven-3.3.9

    On Linux/Unix:

    set MAVEN_HOME=/usr/bin/apache-maven-3.3.9
export MAVEN_HOME

  4. Finally, you will need to set the M2_HOME variable. This tells Maven where to store its repository and settings information.

    On Windows, it is the standard practice to store this information under the user's home directory:

    set M2_HOME=c:\users\jsmith

    The same practice should be used on Linux/Unix:

    set M2_HOME=/home/jsmith
export M2_HOME

    The first time Maven is run, it will create a .m2 directory in the given location.

  5. To ensure that your Maven installation is working correctly, run the following command: 
    mvn --version

    This should return details about the installation.

    Run mvn --version command
    Description of this image

section 5Install the Maven Deployment Plugin

Find the Maven plugin, which is part of the WebLogic Server installation. The installation will have created an Oracle_Home folder inside your installation directory. From there you can navigate to the plugin:

  1. Switch directory to the plugin folder. 
    cd Oracle_Home/oracle_common/plugins/maven/com/oracle/maven/oracle-maven-sync/12.2.1
  2. Install the plugin by executing the following command. 
    mvn install:install-file -DpomFile=oracle-maven-sync-12.2.1.pom -Dfile=oracle-maven-sync-12.2.1.jar

    Then immediately follow with this command.

    mvn com.oracle.maven:oracle-maven-sync:push -DoracleHome=Oracle_Home
  3. You can verify the installation with this command: 
    mvn help:describe -DgroupId=com.oracle.weblogic -DartifactId=weblogic-maven-plugin
    Capture from mvn help describe
    Description of this image

section 6Deploy a Test Application

With your server and Maven configured, you are now ready to deploy a test application from your local machine to your Oracle Java Cloud Service instance.

  1. Download the test application for deploying from here: benefits.war
  2. From your local machine, you're going to execute a Maven command to deploy benefits.war. 
    mvn com.oracle.weblogic:weblogic-maven-plugin:12.2.1-1-0:deploy -Dsource=war_file -Dtargets=server -Duser=user_name -Dpassword=password -Dadminurl=server_address -Dupload=true
    Parameter Description
    -Dsource The source file you are going to deploy.
    -Dtargets The names of the server that you are going to deploy to. You can find the server name from the WebLogic Server administration console.
    -Duser The user name of the WebLogic Server administrator.
    -Dpassword The WebLogic Server administrator's password.
    -DadminUrl The channel address that connects to the server.

    In this example, the maven command would look like this:

    mvn com.oracle.weblogic:weblogic-maven-plugin:12.2.1-1-0:deploy -Dsource=benefits.war -Dtargets=WCP_doma_adminserver -Duser=weblogic -Dpassword=password -Dadminurl=t3://10.252.138.16:7005 -Dupload=true

    When you execute the command, you should get the following result:

    Maven deployment output
    Description of this image

section 7Troubleshoot

You may find that your local maven build fails to connect with the WebLogic installed on the cloud. If your mvn call fails with a connection error, there are a number of things worth checking:

  1. Check the parameters on the command line: 
    mvn com.oracle.weblogic:weblogic-maven-plugin:12.2.1-1-0:deploy -Dsource=benefits.war -Dtargets=adminserver -Duser=weblogic -Dpassword=password -Dadminurl=t3://10.252.138.16:7005 -Dupload=true

    Make sure that the WebLogic user name and password are correct.

    Make sure that your command is pointing to the correct server and the correct IP address.

  2. Are you running through a Virtual Private Network? It is possible that the VPN is blocking the maven connection to your cloud service. If you think this is the case, then you should seek the advice of your network administrator.

more informationWant to Learn More?