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 2008-07-07

Author Mandeep

Version 1.0

Change Reference Initial draft

2008-07-23

Singh Mandeep

1.1

Added extra prerequisites and changed colour for special notes.

2008-07-29 2008-08-07

Singh Aswani Koduru Mandeep

1.1 2.0

Fixed formatting issues Updated for new features of deployment tool

2008-08-21

Singh Mandeep

3.0

Updated for new features of deployment tool

Singh

Reviewers Date

Version

Reviewers

Distribution Date 2008-07-

Version 1.1

Name 10790840.doc

Location http://sultan.int.kn/svn/SealogAirlog/TIM/doc/Framework/trunk/D

23 2008-08-

eliveries/Release1/Iteration3/Deployment/ATLAS_Deployment_ 2.0

Manual.doc http://sultan.int.kn/svn/SealogAirlog/TIM/doc/Framework/trunk/D

10790840.doc

07 2008-08-

eliveries/Release1/Iteration4/Deployment/ATLAS_Deployment_ 3.0

Manual.doc http://sultan.int.kn/svn/SealogAirlog/TIM/doc/Framework/trunk/D

10790840.doc

21

eliveries/Release1/Iteration4/Deployment/ATLAS_Deployment_ Manual_v3.0.doc

Reference Documents Name

Location

Approvals Role

Name

Date

Sign off method (email, phone, personal…)

10790840.doc

02.12.2008

Page 1 of 19

Table of Contents 1 Introduction...................................................................................................................................... .......3 1.1 Purpose of the document................................................................................................................. ......3 1.2 Intended Audience................................................................................................................... ..............3 2 Design................................................................................................................................................. .....4 2.1 Components.................................................................................................................. ........................4 2.1.1 EXTERNAL TOOLS................................................................................................ ........................4 2.1.2 MAVEN Goals........................................................................................................... ......................5 2.1.3 WEBSPHERE ADMIN SCRIPTS......................................................................... ...........................6 3 Usage............................................................................................................................................. ..........7 3.1 Pre-requisites....................................................................................................................................... ..7 3.2 Working................................................................................................................................................ ..7 3.2.1 With Eclipse........................................................................................................... .........................7 3.2.2 External.............................................................................................................................. .............9 4 References............................................................................................................................................ .11 4.1 Setttings.xml.............................................................................................................. ..........................11 4.2 Deploy.xml....................................................................................................................... ....................12 5 New Features of Deployment Tool............................................................................... .......................15 5.1 Version - 0.0.5.................................................................................................................................... ..15 5.2 Version - 0.0.3.................................................................................................................................... ..15 6 FAQs................................................................................................................................. .....................16 6.1 Where are the launchers? I can’t see them................................................................. ........................16 6.2 DataSource creation fails during PrepareApplication? ................................................................... .....16 7 Glossary......................................................................................................................... .......................17

10790840.doc

02.12.2008

Page 2 of 19

1 1.1

Introduction 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.

10790840.doc

02.12.2008

Page 3 of 19

2

Design

2.1

Components

The deployment scripts consist of the following components:

EXTERNAL TOOLS

MAVEN GOALS

StartServer

kndeploy:initialize

StopServer

kndeploy:prepare

Install

kndeploy:server

UnInstall

WEBSPHERE ADMIN SCRIPTS wsadmin: Called from within Maven goals

wsant: called from within Maven goals

StartApplication StopApplication RefreshApplication

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.

10790840.doc

02.12.2008

Page 4 of 19

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: 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

-

deploy.type

To determine the deployment environment

No

eclipse/server/ex ternal

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

Table2: goal parameters

2.1.2.3

kndeploy:server

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

Purpose

Mandatory

Value(s)

Default

server.task

To specify the task to perform

Yes

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

-

Table3: goal parameters

10790840.doc

02.12.2008

Page 5 of 19

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.

10790840.doc

02.12.2008

Page 6 of 19

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 3.2.1

Working 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

10790840.doc

02.12.2008

Page 7 of 19

•

Prepare the application using the launcher: PrepareApplication

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

. It will open the

*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

10790840.doc

02.12.2008

Page 8 of 19

•

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

10790840.doc

02.12.2008

Page 9 of 19

•

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

•

Run the following command: mvn kndeploy:prepare -Ddeploy.type=external -Ddeploy.xml=<path to deploy.xml> •

•

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.

10790840.doc

02.12.2008

Page 10 of 19

4 4.1

References 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/settings1.0.0.xsd"> <proxies> <proxy> optional true <protocol>http proxy-europe.int.kn <port>8080 <profiles> <profile> dev true Niagara http://niagara.int.kn:8081/artifactory/repo default Niagara http://niagara.int.kn:8081/artifactory/repo default dev com.kn.maven.plugins

10790840.doc

02.12.2008

Page 11 of 19

4.2

Deploy.xml

<deploy name="MyApp"> <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" /> name="jnlp.title" value="Atlas" /> name="jnlp.vendor" value="Kuehne + Nagel" /> name="jnlp.homepage" value="http://www.kn-

02.12.2008

Page 12 of 19

portal.com" /> <property name="jnlp.description" value="Atlas Framework" /> <property name="jnlp.mainclass" value="com.dsia.atlas.rcli.core.ApplicationManager" /> <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">

10790840.doc

02.12.2008

Page 13 of 19

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

Purpose

Notes

application.

-

application..version

-

This version should match the version in ear.xml

jdbcprovider.

-

-

jdbcprovider..name

-

This name is used for creating JDBC Provider in Websphere. *This should not contain spaces or special characters.

jdbcprovider..drivername

-

-

jdbcprovider..driverclass

-

-

jdbcprovider..driverpool

-

-

jdbcprovider..driverlib

-

-

datasource.

-

-

datasource..name

-

-

datasource..jndiname

JNDI name for the datasource

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

datasource..options

-

-

datasource..url

URL for connection to datasource

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

datasource..user

Username for datasource access

-

datasource..password

Password for datasource access

-

datasource..schema

Schema for datasource access. Generally the same as username.

-

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

10790840.doc

02.12.2008

Page 14 of 19

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.

10790840.doc

02.12.2008

Page 15 of 19

6 6.1

FAQs 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 AllOkOk. 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.

10790840.doc

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

02.12.2008

Page 16 of 19

7

Glossary

10790840.doc

02.12.2008

Page 17 of 19