ATLAS Deployment Manual v3.0

DEPLOYMENT MANUAL

PROJECT “SEALOG/AIRLOG”

Author: Mandeep Singh

Version: 3.0

Date: August 21st 2008

Document Control

Change Record

Date Author Version Change Reference

2008-07-07 Mandeep

Singh

1.0 Initial draft

2008-07-23 Mandeep

Singh

1.1 Added extra prerequisites and changed colour for special notes.

2008-07-29 Aswani Koduru 1.1 Fixed formatting issues

2008-08-07 Mandeep

Singh

2.0 Updated for new features of deployment tool

2008-08-21 Mandeep

Singh

3.0 Updated for new features of deployment tool

Reviewers

Date Version Reviewers

Distribution

Date Version Name Location

2008-07-

23

1.1 document.doc http://sultan.int.kn/svn/SealogAirlog/TIM/doc/Framework/trunk/

Deliveries/Release1/Iteration3/Deployment/

ATLAS_Deployment_Manual.doc

2008-08-

07



ATLAS_Deployment_Manual.doc

2008-08-

21



ATLAS_Deployment_Manual_v3.0.doc

Reference Documents

Name Location

Approvals

Role Name Date Sign off method

(email, phone, personal…)

document.doc 11.04.2023 Page 1 of 20

Role Name Date Sign off method

(email, phone, personal…)


Table of Contents

1 Introduction........................................................................................................................................ 4

1.1 Purpose of the document..................................................................................................................4

1.2 Intended Audience............................................................................................................................ 4

2 Design................................................................................................................................................. 5

2.1 Components..................................................................................................................................... 52.1.1 EXTERNAL TOOLS................................................................................................................... 52.1.2 MAVEN Goals............................................................................................................................ 62.1.3 WEBSPHERE ADMIN SCRIPTS...............................................................................................7

3 Usage................................................................................................................................................... 8

3.1 Pre-requisites.................................................................................................................................... 8

3.2 Working............................................................................................................................................. 83.2.1 With Eclipse............................................................................................................................... 83.2.2 External................................................................................................................................... 10

4 References........................................................................................................................................ 12

4.1 Setttings.xml................................................................................................................................... 12

4.2 Deploy.xml...................................................................................................................................... 13

5 New Features of Deployment Tool..................................................................................................16

5.1 Version - 0.0.5................................................................................................................................ 16

5.2 Version - 0.0.3................................................................................................................................ 16

6 FAQs.................................................................................................................................................. 17

6.1 Where are the launchers? I can’t see them....................................................................................17

6.2 DataSource creation fails during PrepareApplication?....................................................................17

7 Glossary............................................................................................................................................. 18


1 Introduction

1.1 Purpose of the document

To impart knowledge about using deployment scripts for applications based on the Atlas framework.

1.2 Intended Audience

This document is intended for all developers using the Atlas framework for application development, all team leads, project leads, build/release managers and whosoever is interested in learning about the scripts.


2 Design

2.1 Components

The deployment scripts consist of the following components:

2.1.1 EXTERNAL TOOLS

The external tools depend on ‘Maven’ and ‘wsant’ to interact with the server. These tools call Maven and execute the goal ‘kndeploy:server’ to perform server tasks.

1. StartServer

To start the Websphere server

2. StopServer

To stop the server

3. Install

To install the application in the server

4. UnInstall

To uninstall the application from the server

5. StartApplication

To start the application on server

6. StopApplication

To stop the application on the server

7. RefreshApplication

To refresh the application on server to reflect the changes made. *NOTE - Not applicable for changes made to EJBs.


EXTERNAL TOOLS

StartServer

StopServer

Install

UnInstall

StartApplication

StopApplication

RefreshApplication

MAVEN GOALS

kndeploy:initialize

kndeploy:prepare

kndeploy:server

WEBSPHERE ADMIN SCRIPTS

wsadmin: Called from within Maven goals

wsant: called from within Maven goals

2.1.2 MAVEN Goals

The Maven goals are executed using Maven plugins. Whenever the goal is fired, maven searches for corresponding plug-in in the local repository. If not found it downloads it from the artifactory defined in settings.xml (see 4.1) and stores it in the local repository.

2.1.2.1 kndeploy:initialize

The kndeploy:initialize goal uses the following parameters to initialize the application environment:

Parameter Purpose Mandatory Value(s) Default

deploy.xml To specify the location of the deploy.xml file

Yes Full path of the deploy.xml file

-

Table1: goal parameters

2.1.2.2 kndeploy:prepare

The kndeploy:prepare goal uses the following parameters to prepare the application:


deploy.xml To specify the location of the deploy.xml file

Yes Full path of the deploy.xml file

-

deploy.type To determine the deployment environment

No eclipse/server/external

server

deploy.tests To execute tests while running a maven build

No true/false false

deploy.buildAtlas To determine whether Atlas should be build. When set to false, this speeds up operation for a developer who does not change any code in Atlas Framework. An application developer should always set this to false.

No true/false false

deploy.createDS To create datasource on the Websphere server

No true/false false


2.1.2.3 kndeploy:server

The kndeploy:server goal is used to interact with the server:


server.task To specify the task to perform

Yes StartServer / StopServer / InstallApp / UnInstallApp / StartApp / StopApp / RefreshApp

-



2.1.3 WEBSPHERE ADMIN SCRIPTS

These are used by the external tools and Maven plug-ins internally and are used to get control of the Websphere application server.


3 Usage

3.1 Pre-requisites

User should define WAS_HOME as a system environment variable and this should point to the user’s installation directory of Websphere V6.1 server.

Initialize Websphere admin scripts. This is a one time process.

Open command prompt

Go to directory <WAS_HOME>\bin

Run the command: wsadmin -lang jython

After command executes, exit command prompt

Maven 2.0.7( or higher) must be installed on the users system and should be present in the system PATH. M2_HOME environment variable must be set.

Proper settings.xml should be used for Maven (see 4.1). The user can compare and update the settings.xml file using the one included in section 4.1

For Eclipse environment, Eclipse Maven plugin should be present. This can be downloaded from http://m2eclipse.sonatype.org/update/

The project to be deployed should have a standard structure based on the framework and should be configured properly.

3.2 Working

3.2.1 With Eclipse

Following are the steps to deploy an application using eclipse:

Modify the deploy.xml (see 4.2) file as per the deployment environment.

Initialize the environment using the launcher: Initialize

*NOTE - It is mandatory to initialize the environment whenever the user makes changes to server specific properties in deploy.xml or changes the application name in deploy tag of deploy.xml. This is necessary to have the changes reflected.

Start the server using the launcher: StartServer


http://m2eclipse.sonatype.org/update/

Prepare the application using the launcher: PrepareApplication

To change the parameters to be passed to this launcher select . It will open the following screen where the parameters can be edited. (See 2.1.2.1).

*NOTE: Selecting the deploy.type

1. eclipse – this is used for development purposes and would not deploy the client component of the application to the server. The developer can make changes to the client side in eclipse and see the impact directly.

2. server – this is used to deploy the application on server completely including the client component. The developer can then access the application through a JNLP URL which would resemble: http://localhost:port/<ApplicationName>/webstart/launch.jnlp. When application is deployed on the server this way, the Refresh Application task will not be valid and should not be used.

3. external – this is used for creating a final ear which can be deployed on any server. If used through eclipse, this would create the final ear in the workspace under the folder .output


Install the application using the launcher: Install

Start the application on server using the launcher: StartApplication

Optionally, if required, the user can stop the application on server using the launcher: StopApplication

If the user makes some changes in the common and server projects of the application, then to have these changes reflected, the user should run the following launcher: RefreshApplication

*NOTE - RefreshApplication is not applicable for changes made to EJBs. In this case the user should run the following launchers: PrepareApplication, UnInstall, and Install. Also, this should not be used when deploy.type used is server.

The user can Uninstall the application if required using the launcher: UnInstall

3.2.2 External

Following are the steps to prepare an application for deployment on any external server.

To the root folder of your application add the project AtlasEAR. After adding this project the structure should look somewhat like


mvn kndeploy:prepare -Ddeploy.type=external -Ddeploy.xml=<path to deploy.xml>

Open command prompt and navigate to the root of the above shown project structure.

Run the following command:

When the above command executes successfully, the final ear can be found in the directory .output at the root of the above shown project structure.

This final ear can be deployed onto any server. For this ear deployment to work successfully, the deployer has to ensure that the data sources are configured correctly on the external server.


4 References

4.1 Setttings.xml


<settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

<proxies>

<proxy><id>optional</id><active>true</active><protocol>http</protocol><host>proxy-europe.int.kn</host><port>8080</port>

</proxy></proxies>

<profiles>

<profile><id>dev</id><activation>

<activeByDefault>true</activeByDefault></activation><repositories>

<repository><id>Niagara</id>

<url>http://niagara.int.kn:8081/artifactory/repo</url><layout>default</layout>

</repository></repositories><pluginRepositories>

<pluginRepository><id>Niagara</id>

<url>http://niagara.int.kn:8081/artifactory/repo</url><layout>default</layout>

</pluginRepository></pluginRepositories>

</profile></profiles>

<activeProfiles>

<activeProfile>dev</activeProfile></activeProfiles>

<pluginGroups>

<pluginGroup>com.kn.maven.plugins</pluginGroup></pluginGroups>

</settings>

4.2 Deploy.xml


<?xml version="1.0" encoding="UTF-8"?>

<deploy name="MyApp">

<applications>

<application id="Atlas" version="1.10.4-SNAPSHOT" /></applications>

<properties>

<property name="server.home"

value="C:/WebSphere/AppServer/profiles/AppSrv01" /><property name="profile" value="AppSrv01" /><property name="hostname" value="localhost" /><property name="logicalhostname" value="localhost" /><property name="wasinstance" value="localhost" /><property name="server" value="server1" /><property name="profile" value="AppSrv01" /><property name="cell" value="DEW08074Node01Cell" /><property name="node" value="DEW08074Node01" /><property name="soap.user" value="admin" /><property name="soap.password" value="password" /><property name="virtual.host.name" value="default_host" /><property name="maskid" value="DEMO" />

<property name="http.port" value="9080" /><property name="bootstrap.port" value="2809" /><property name="soap.port" value="8880" />

<property name="Atlas.EJBjndi.prefix" value="Atlas" />

<property name="Log4j.rootLogValue" value="error" />

<property name="ijump.server" value="http://host:port/iJUMP/"

/><property name="ijump.lookAndfeel"

value="com.kn.coolgray.laf.KNCoolGrayLookAndFeel" /><property name="ijump.user" value="abc" /><property name="ijump.pwd" value="xyz" />

<property name="atlas.contextroot" value="AtlasWeb" />

<property name="jnlp.title" value="Atlas" /><property name="jnlp.vendor" value="Kuehne + Nagel" /><property name="jnlp.homepage" value="http://www.kn-


portal.com" /><property name="jnlp.description" value="Atlas Framework" /><property name="jnlp.mainclass"

value="com.dsia.atlas.rcli.core.ApplicationManager" />

 

</properties>

<jdbcprovider id="OracleDriver"

name="OracleJDBCDriver" drivername="OracleDriver" driverclass="oracle.jdbc.driver.OracleDriver"

driverpool="oracle.jdbc.pool.OracleConnectionPoolDataSource" driverlib="C:/DriversDB/Oracle/ora92/jdbc/lib/ojdbc14.jar">

<datasource id="regularDS" name="regularDataSource"jndiname="regularDS" options=""url="jdbc:oracle:thin:@host:port:SID" user="abc"password="xyz" schema="abc" />

<datasource id="purgeDS" name="purgeDataSource" jndiname="purgeDS"options="" url="jdbc:oracle:thin:@host:port:SID" user="abc"password="xyz" schema="abc" />

</jdbcprovider>

</deploy>

The following properties are available from deploy.xml for replacement in ear.xml of the project

Property Purpose Notes

application.<id> -

application.<id>.version - This version should match the version in ear.xml

jdbcprovider.<id> - -

jdbcprovider.<id>.name - This name is used for creating JDBC Provider in Websphere. *This should not contain spaces or special characters.

jdbcprovider.<id>.drivername - -

jdbcprovider.<id>.driverclass - -

jdbcprovider.<id>.driverpool - -

jdbcprovider.<id>.driverlib - -

datasource.<id> - -

datasource.<id>.name - -

datasource.<id>.jndiname JNDI name for the datasource

This jndiname is used for creating datasource in Websphere. *This should not contain spaces or special characters

datasource.<id>.options - -

datasource.<id>.url URL for connection to datasource

jdbc:oracle:thin:@host:port:sid

datasource.<id>.user Username for datasource access

-

datasource.<id>.password Password for datasource access

-

datasource.<id>.schema Schema for datasource access. Generally the same as username.

-

NOTE - All other properties are available as specified under <properties></properties>. The user can add as many properties as required.


5 New Features of Deployment Tool

5.1 Version - 0.0.5

Developer can do a direct and complete deployment on local Websphere through Eclipse. The application can then be accessed in the same way using JNLP URL, as it would be after actual deployment.

The deployment is now possible on a secured server. For this the user has to specify the correct SOAP port, username and password in the deploy.xml file.

If a task fails, the tool throws an error unlike before where in some cases, the status showed up as BUILD SUCCESSFUL even after the task failed.

The tool can now prepare an application for external deployment. The EAR thus created can be deployed to any server directly.

The deploy.xml now contains properties to configure the JNLP downloader. E.g. jnlp.title, jnlp.vendor, jnlp.homepage, jnlp.description, jnlp.mainclass.

5.2 Version - 0.0.3

No need for application developer to use Framework source code. Only AtlasEAR project and Launchers need to be shared. The AtlasEAR project will have all property and xml templates under (src/main/resources)

In deploy.xml you can specify the application name now. The application will be deployed on server with this name. If no name is given, the default is ‘Local’ e.g. <deploy name="MyApp">

Datasource Update – If the user/password information changes, the createDS component of prepareApplication automatically updates the existing datasource.

Initialize launcher – this initializes the environment for running other launchers. So needs to be run one time before any other launcher is used. Also if there is change in deploy.xml for Websphere properties or application name (<deploy name="MyApp">), the environment should be re-initialized using the Initialize launcher.

RefreshApplication launcher – This launcher can now be run directly to refresh the application on server for changes in non-EJB and non-WEB projects. (In earlier versions the developer had to first prepare the application and then refresh.)

No need of build.xml and build.properties in launchers folder.


6 FAQs

6.1 Where are the launchers? I can’t see them.

Normally if the Launcher project is present in the workspace, the launchers should be visible under

. The launchers invisible problem happens generally when a fresh workspace is created. To see the launchers do the following:

a. Open: .

b. Select: Organize Favourites…Add…Select AllOkOk.

c. Do this for all categories of launchers.

The launchers should be visible now.

6.2 DataSource creation fails during PrepareApplication?

This can happen because of the following reasons:

a. Server node is incorrect in deploy.xml

b. The variables for ‘jdbcprovider name’ or ‘datasource jndiname’ in deploy.xml, contain spaces or special characters.

c. In WebSphere Admin Console, under WebSphere Variables, the variable ORACLE_JDBC_DRIVER_PATH is not defined properly at the node level or the value of this variable does not point to the correct ojdbc14.jar


7 Glossary