wdeploy: Business Objects Deployment tool

Objective: To deploy Business Objects web applications.

This implementation is ANT-based with some javascript helpers.

Usage:

wdeploy <app or web server type> [<options>] <action>

Application and Web servers:
    Apache 2 (web server type: apache)
    Sun Java System Web Server 6 (web server type: iplanet)
    Tomcat 5.0 (app server type: tomcat)
    Websphere 5.1(app server type: websphere)
    Websphere 6.0 (app server type: websphere6)
    Sun Java Application Server 8.1 (app server type: sunone8)
    WebLogic 8.1 (app server type: weblogic81)
    WebLogic 9 (app server type: weblogic9)

Supported distributed mode configurations:
    Using Apache: Tomcat, Websphere, WebLogic.
    Using Sun Java System Web Server: Tomcat, WebSphere, Weblogic, Sun Java System Application Server

Actions are:

    listapps      - List all available applications described in the apps directory.
    buildwar      - Create resources for the specified application.
    predeploy     - Create resources and the configuration files for the specified application.
    deploy        - Create resources and the configuration files for the specified application, and deploy the application.
    deployonly    - Deploy a predeployed application.
    deployall     - Deploy all available applications described in the apps directory.
    buildall      - Build all available applications described in the apps directory.
    predeployall  - Pre-deploy all available applications described in the apps directory.
    deployonlyall - Deploy all predeployed applications.
    version       - Display the wdeploy version.

Options are:

    -DAPP=<application> - Work on the specified application using the apps/<application>.properties file.
    -Dwork_dir=<work dir> - The directory where you store information. Defaults to $INSTALLDIR/deployment/workdir.
    -Das_mode=distributed|standalone - The deployment mode.
    -Das_dir=<app server dir> - The application server installation directory (for WebLogic, the directory holding startWebLogic.sh).
    -Das_admin_port=<port> - The administration port of the application server [weblogic81, weblogic9, sunone8].
    -Das_admin_username=<user name> - The administrator login on the web application server [weblogic81, weblogic9, sunone8].
    -Das_admin_password=<passwd> - The administrator password on the web application server [weblogic81, weblogic9, sunone8].
    -Das_instance=<instance> - The instance to install the application to [weblogic81, weblogic9, websphere, websphere6, sunone8, tomcat].
    -Das_virtual_host=<vhost> - The virtual host to link the application to [websphere, websphere6].
    -Das_admin_is_secure=[true|false] - The asadmin command needs --secure or not. Defaults to false [sunone8].
    -Das_service_name=<service name> - The name of the service, as registered in Windows [tomcat].
    -Denforce_file_limit=[true|false] - Give a hint to wdeploy on the behaviour of the application server when a large application is deployed. Defaults do false. Not set except for [sunone8, websphere, websphere6]
    -Dws_type=[apache|iplanet] - The kind of web server to deploy to, in distributed mode.
    -Ddeployment_dir=<dir> - The directory to copy the web server resources to, in distributed mode.
    -Dws_dir=<dir> - The directory that holds the web server, in distributed mode.
    -Dconnector_type=[tomcat|websphere|websphere6|sunone8|weblogic81|weblogic9] - The web server connector to configure.
    -Dconnector_name=<object name> - The name of the object in obj.conf describing the connector module to the application server [iplanet].
    -Dws_instance=<instance> - The web server instance that will serve the requests, in distributed mode [websphere6].
    -DXMLRegName=<registry name> - The name of the registry to assign to a server [weblogic9]
    -DXMLRegDocBuilderFactory=<class name> - The name of the class in the registry that handles document building [weblogic9]
    -DXMLRegSAXParserFactory=<class name> - The name of the class in the registry that handles XML parsing [weblogic9]
    -DXMLRegTransformerFactory=<class name> - The name of the class in the registry that document transformation [weblogic9]

Examples :

wdeploy tomcat listapps
    Lists all available applications.

wdeploy sunone8 deployall
    Deploys all applications for Sun Java Application Server 8.1 (all configuration parameters are set in the config.sunone8 file).

wdeploy tomcat -DAPP=infoview -Das_mode=distributed -Das_dir=/space3/tomcat -Das_instance=localhost -Dws_type=apache -Ddeployment_dir=/tmp -Dws_dir=/space3/apache deploy
    Deploys the Infoview application in Tomcat, in distributed mode. Tomcat is installed in /space3/tomcat, Instance is 'localhost'. Web server is Apache, installed in /space3/apache. Resources are installed in /tmp/infoview ($deployment_dir/$APP), and the directory is mapped to the application context root.

wdeploy weblogic81 -Das_dir=/space3/pceffis/bea/user_projects/domains/mydomain -DAPP=infoview -Das_mode=distributed buildwar
    Create the WAR file in distributed mode for the Infoview application, packaged for WebLogic 8.1.

wdeploy apache -DAPP=infoview -Das_mode=distributed -Dconnector_type=weblogic81 -Ddeployment_dir=/tmp/apache -Dws_dir=/space3/pceffis/apache deploy
    Deploys the static resources of the Infoview application in Apache, configuring the connector for WebLogic 8.1.

wdeploy websphere6 -DAPP=infoview -Das_mode=distributed -Dws_instance=webserver1 deploy
    Deploys the dynamic resources of the Infoview application in Websphere 6, regenerates plugin configuration for the web server.
    

Important:

You must describe your application server installation in a config.<appservertype> or config.properties file.

JAVA_HOME must be set in the environment for wdeploy to work. However, when using the UNIX wdeploy, when the application server is either Sun Java Application Server, WebLogic or WebSphere, and when the config.<appservertype> holds correct information, wdeploy will try to use the application server's JAVA_HOME.

Samples config.sunone8, config.weblogic81, config.weblogic9, config.websphere, config.websphere6, config.apache, config.iplanet, and config.tomcat are provided.

Application deployment information is stored in apps/<application>.properties files.

You can edit these files to change default values, or add your own application description.


Application properties file values:

warfile                    the name of the application WAR file present in war_dir [MANDATORY]
zipfile                    the name of the static resource file for the application present in war_dir [OPTIONAL]
appvdir                    the context root of the application [MANDATORY]
addtoclasspath             the line to add to the classpath of the application server [OPTIONAL]
addtolibpath               the line to add to the libpath of the application server [OPTIONAL]
buildfile                  the name of an XML file that contains additional configuration information [OPTIONAL]
war_dir                    the directory holding the 'warfile' for UNIX platforms [OPTIONAL]
win_war_dir                the directory holding the 'warfile' for Windows [OPTIONAL]
file_limit_reached         set to 'true' for an application that hold a large number of file. This triggers a special for some web application servers (sunone8, websphere, websphere6) [OPTIONAL]
dont_split_content         set to 'true' for an application that doesn't support distributed mode. This triggers a special for some web application servers (websphere, websphere6) [OPTIONAL]
wdeploy.prop.count         the number of properties to set in the application server's JVM (positive integer) [OPTIONAL]
wdeploy.prop<i>.name       the name of the property #<i>
wdeploy.prop<i>.applies_to the space-separated list of platforms the property applies to
wdeploy.prop<i>.value      the value of this property. If the property cannot get fully expanded (if it depends on other properties, one of which is not set), the property will not be set. Supported platforms: solaris_sparc, aix_rs6000, hpux_pa-risc, linux_x86 and win32_x86

For an example of wdeploy.prop.count, see apps/infoview.properties or apps/styles.properties.


Configuration information:

* for Apache:
  file ${ws_dir}/conf/bobj.${APP}.conf is created, containing, for each application, connector configuration information and:

Alias /${appvdir} "${deployment_dir}/${APP}"
<Directory "${deployment_dir}/${APP}">
  Options FollowSymLinks
</Directory>

  File ${ws_dir}/conf/httpd.conf is modified to include this file.
* for Sun Java System Web Server:
  file ${ws_dir}/obj.conf is modified, for each application the following line is added:

NameTrans fn=pfx2dir from="${appvdir}" dir="${deployment_dir}/${APP}"

* for Sun Java Application Server:
  Properties are added as JVM options. Library path modifications are done modifying JVM's native library path suffix. The java.policy file is modified, to add some permissions:
    grant {
      permission java.util.PropertyPermission "*", "read,write";
      permission java.lang.RuntimePermission "createClassLoader";
      permission java.lang.RuntimePermission "getClassLoader";
      permission java.io.FilePermission "<OLAPi root dir>", "read,write,execute";
      permission java.net.SocketPermission "*", "connect,listen,accept,resolve";
    };
* for Tomcat:
  files added to the libpath are dropped in ${as_dir}/shared/lib
  file ${as_dir}/bin/bobjeEnv.${APP}.[sh|bat] is created, containing libpath modifications, and JAVA_OPTS modifications to add the application's properties. File ${as_dir}/bin/catalina.[sh|bat] is modified to include this file. Tomcat must be restarted to take changes into account.
* for WebLogic 8.1:
  file ${as_dir}/bobjeEnv.${APP}.[sh|cmd] is created, containing classpath, libpath, and JAVA_OPTIONS modifications. File ${as_dir}/startWebLogic.[sh|cmd] is modified to include this file. When modifications are made to the startWebLogic.[sh|cmd] file, WebLogic is restarted. WebLogic must be able to restart without asking for a username/password for the actual deployment to take place.
* for WebLogic 9:
  files to add to the classpath are bundled in the application (added to WEB-INF/lib). File ${as_dir}/bin/bobjeEnv.${APP}.[sh|cmd] is created, containing libpath and JAVA_OPTIONS modifications. File ${as_dir}/bin/startWebLogic.[sh|cmd] is modified to include this file.
  cf WebLogic 8.1, plus an XML Registry gets created and assigned to the application server.
* for WebSphere 5 and WebSphere 6:
  files to add to the classpath are bundled in the application (added to WEB-INF/lib). Properties are added as JVM custom properties. Library path modifications are done modifying the environment of the JVM. Web Server plugin gets automatically regenerated.


Troubleshooting:

Weblogic 9:
As a XML registry is assigned to the server, deploying the applications into the server where the Weblogic administration application resides might breaks this application. Deploying in a slave application server is safer.


If you get the following message when deploying in Websphere:

  WASX7017E: Exception received while running file "workdir/websphere/application/install.scr"; exception information: com.ibm.websphere.management.exception.ConfigServiceException
  com.ibm.websphere.management.exception.ConnectorException
  org.apache.soap.SOAPException: [SOAPException: faultCode=SOAP-ENV:Client; msg=Read timed out; targetException=java.net.SocketTimeoutException: Read timed out]

Try raising or removing the SOAP connection timeout set by the property com.ibm.SOAP.requestTimeout in:
* the $WASINSTALLDIR/properties/soap.client.props file, for WebSphere 5.1.x
* the $WASINSTALLDIR/profiles/<profile>/properties/soap.client.props file, and probably $WASINSTALLDIR/profiles/<profile>/temp/soap.client.props, for WebSphere 6.x


Sun Java System Web Server connector information:
* for tomcat: see http://tomcat.apache.org/connectors-doc/webserver_howto/nes.html and http://tomcat.apache.org/connectors-doc/reference/workers.html
  Add to obj.conf

    <Object name="jknsapi">
      ObjectType fn=force-type type=text/plain
      Service fn="jk_service" method="*" worker="worker1"
    </Object>

  where 'jknsapi' is the connector_name to pass to wdeploy. Don't forget that the connection_pool_size cannot be auto-sensed when using iplanet as web server, you have to set it manually in the workers.properties file
* for WebLogic: see http://e-docs.bea.com/wls/docs81/plugins/nsapi.html
  Add to obj.conf something like

    <Object name="weblo">
      Service fn="wl_proxy" WebLogicHost="localhost" WebLogicPort="7001"
    </Object>

  where 'weblo' is the connector_name to pass to wdeploy
* for WebSphere: see http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/tins_manualWebIPL.html
* for Sun Java Application Server: see http://docs.sun.com/source/819-0902-05/rpp61.html
  and http://swforum.sun.com/jive/thread.jspa?forumID=16&threadID=53321


Known issues:

Some problem persist in distributed mode with applications dswsbobje and styles, on Weblogic and Sun Java Application Server.
Please deploy dswsbobje on Weblogic following this application's release notes, even when deploying in standalone mode.
