Advanced server deployment features
The Build and Deployment tool provides many advanced server deployment features to support more complex configurations. Ensure that you review this page to find and implement features that may improve your server deployment process.
- Remote server deployment
- Loading procedural SQL files
- Loading data using the Data Load utility
- Setting the maximum heap size for wsadmin
- Setting virtual host for new Web modules
- Mapping references for EJB modules
- Deleting files during partial application update
- E-mail notifications of deployment status
- Additional logging and tracing
Remote server deployment
The server deployment process can be configured to deploy remotely to any node in a WebSphere Commerce topology configuration, provided that the server deployment system satisfies all prerequisites required by the Build and Deployment tool. Remote deployment is used by the centralized deployment feature in the build process.
To deploy to a remote database node, configure the database-related properties in WCBD_deploy_server_dir/deploy-target-env.properties as follows:
- Set the following properties according to the local environment
on the build system:
jdbc.driver
jdbc.driver.path
- Set the following properties according to the remote WebSphere
Commerce database:
db.name
db.schema.name
jdbc.url
datasource.jndi.name
To deploy to a WebSphere Application Server node or cluster on which the WebSphere Commerce application is deployed, configure the properties in WCBD_deploy_server_dir/deploy-target-env.properties related to WebSphere Application Server as follows:
- Set the following properties according to the local environment
on the build system:
was.home
was.profile.name
was.jvm.max.memory
- Set the following properties according to the remote environment
on which the WebSphere Commerce application is deployed:
was.application.name
was.use.dmgr
was.host.list
was.port
Deployment to a remote Web server node is handled by the static Web assets deployment step in the server deployment process. Likewise, deployment to a remote WebSphere Commerce server node (that is the node with the WebSphere Commerce installation) is handled by the WebSphere Commerce configuration file synchronization step and the Data Load utility customization deployment step in the server deployment process. Refer to comments in the configuration files and sample scripts for details.
If you have an existing firewall between your two machines, you might need to open the SOAP port and the WebSphere Application Server administration port, so that the build machine can communicate with the stand alone server it is deploying to. Alternatively, if you have a firewall, you might want to copy your deployment package to the remote machine and run the deployment locally instead of using the remote deployment function.
Loading procedural SQL files
Many database management systems support procedural
extensions for SQL. Statements written in procedural SQL often require
a different delimiter than the default one for regular SQL statements.
The deployment process supports loading procedural SQL files with
a procedural statement delimiter based on a keyword identifier in
the file name. By default, if the base name if a SQL file contains
the keyword identifier procedural
, it will be loaded
with the procedural statement delimiter @
. These
can be configured as required by changing the procedural.sql.file.name.id
and procedural.sql.delimiter
properties
in WCBD_deploy_server_dir/deploy-target-env.properties respectively.
Loading data using the Data Load utility
The Data
Load utility provides an efficient data load solution based
on business objects. The deployment process supports loading data
using the Data Load utility, which is useful for loading test data
and administrative data such as member data. Similar to how other
data files are organized in the repository, data and configuration
files used by the Data Load utility are put into the dataload subdirectory
of the DataLoad
project, which is further organized
into the common and target-specific subdirectories. The build process
will then include these files into the deployment packages. Unless
configured otherwise, all files with the name wc-dataload.xml are
included for loading. Additional parameters for the Data Load utility
command can be included by setting the dataload.params
property
in WCBD_deploy_server_dir/deploy-target-env.properties.
Refer to the Server
deployment configuration properties topic for more information
on the properties specific to the Data Load utility.
It is recommended
that you follow the Data Load best practices as you develop and organize
Data Load data and configuration files. To promote reuse of properties
defined in the deployment configuration properties file, especially
those of the database, consider using variable substitutions by referencing
variables in the configuration files and passing the variable values
with the dataload.params
property mentioned above.
Setting the maximum heap size for wsadmin
Depending on the size of the
WebSphere Commerce application with the customization, the application
update process may fail due to wsadmin running out of memory. Typically
this does not occur, however if it does, open WCBD_deploy_server_dir/deploy-target-env.properties with
a text editor and set the was.jvm.max.memory
property
to a higher value than the default (1024M).
Setting virtual host for new Web modules
The WebSphere Commerce development environment
uses a standard virtual host WC_default_host
for
Web modules. However, in a server environment, this virtual host does
not exist and a different virtual host specific for the WebSphere
Commerce instance is required. In response this behaviour, the Build
and Deployment tool provides the option to set virtual hosts for new
Web modules that are deployed by the server deployment process. To
set a virtual host, open WCBD_deploy_server_dir/deploy-target-env.properties with
a text editor and set the virtual.host.mapping.list
property
according to the comment in the file.
Mapping references for EJB modules
Some EJB modules require references to operate. For example, the WebSphere Commerce service module may contain a EJB module that contains resource references to the WebSphere Commerce data source, which differ between WebSphere Commerce instances and the WebSphere Commerce development environment. For this reason, the Build and Deployment tool provides a mean to map EJB references and resource references to EJBs in the server deployment process.
A mapping option file is used to define the mappings to be applied during the WebSphere Commerce application update. The file , in comma-separated values (CSV) format, lists parameters that describes an individual mapping. The parameters are specified, in order:
- The module name, for example
Project-Server
- The mapping option, for example
MapEJBRefToEJB
- Any other parameters required by the specified mapping option
Mapping Option | Parameter | Required |
---|---|---|
MapEJBRefToEJB | EJB name | Yes |
Resource reference | Yes | |
Class | Yes | |
Target resource JNDI name | Yes | |
MapResRefToEJB | EJB name | Yes |
Resource reference | Yes | |
Resource type | Yes | |
Target resource JNDI name | Yes | |
Login configuration name | No* | |
Properties | No* | |
Extended data source properties | No* |
* The optional values must be set to the empty value in the CSV file.
These option-specific parameters correspond to a subset of the AdminApp object update options for the wsadmin scripting interface. For more information, see Options for the AdminApp object install, installInteractive, edit, editInteractive, update, and updateInteractive commands using wsadmin scripting. For convenience, the following substitution tokens can be used so that some parameters do not need to be hardcoded outside of the server deployment configuration:
Token | Substituted value |
---|---|
@WC_DATA_SOURCE_JNDI_NAME@ |
The value of the datasource.jndi.name property
in the server deployment configuration file. |
The following is an example of the mapping option file
that maps the WebSphere Commerce data source to the Project and ProjectServicesImpl
beans
in the Project-Server
EJB module:
Project-Server,MapResRefToEJB,Project,jdbc/WCDataSource,javax.sql.DataSource,@WC_DATA_SOURCE_JNDI_NAME@,,,
Project-Server,MapResRefToEJB,ProjectServicesImpl,jdbc/WCDataSource,javax.sql.DataSource,@WC_DATA_SOURCE_JNDI_NAME@,,,
After
following the above instructions to create the mapping option file,
place it in WCBD_deploy_server_dir. Then open WCBD_deploy_server_dir/deploy-target-env.properties with
a text editor and set the mapping.option.file
property
to the file path.
Deleting files during partial application update
The partial application update functionality from WebSphere Application Server supports the deletion of files from an application using the special ibm-partialapp-delete.props files. Since the Build and Deployment tool leverages partial application update, this file deletion feature can also be used if required.
In most cases, deleting files from the WebSphere Commerce application is a one-time task. As such, it is recommended that the ibm-partialapp-delete.props files are not checked into the repository permanently. Instead, when files need to be deleted from the application, the ibm-partialapp-delete.props files can be added to WCBD_deploy_server_dir/source/wc.ear after the server deployment package is installed. These files will be included into the partial application archive file for update in the server deployment process. Depending on which module scope the files to be deleted are located, the ibm-partialapp-delete.props file may need to be created at different location. For details on how to create and structure the ibm-partialapp-delete.props files, see Adding to, updating, or deleting part of an application through programming.
E-mail notifications of deployment status
The server deployment process can be configured to send out e-mail notifications upon success and failure. For failure notifications, the archived deployment log file is attached for convenience. Follow the steps below to enable this functionality in the deployment settings:
- Open WCBD_deploy_server_dir/deploy–target-env.properties with a text editor and set the properties under the "Properties for e-mail notification" section accordingly. Refer to the comments in the file for details.
- If the SMTP server requires authentication, open WCBD_installdir/deploy-target-env.private.properties file
with a text editor and set the following properties.
mail.user
mail.password
Additional logging and tracing
Ant
provides both a verbose and a debug option to provide additional tracing
that may be useful for problem determination. To enable verbose mode,
provide either the-v
or -verbose
option
when calling the wcbd-ant.bat or wcbd-ant command
to run the server deployment process. Likewise, to enable debug mode,
provide either the-d
or -debug
option
when calling the wcbd-ant.bat
or wcbd-ant
command
to run the server deployment process.
static-web-deploy
target
in the server deployment process:[exec] [Wed, 21 Jul 2010 15:58:06 -0400] wcbd-deploy > static.web.deploy [exec] [exec] static.web.deploy: [exec] [echoNL] Deploying web server assets with C:\IBM\WCDE_ENT70\wcbd\deploy-server-workspace\wcbd-deploy-server-empty/static-web-deploy-local.xml. [exec] [Wed, 21 Jul 2010 15:58:06 -0400] static-web-deploy-local > all [exec] [exec] all: [exec] [copy] Copying 3 files to C:\web-server-root [exec] [Wed, 21 Jul 2010 15:58:06 -0400] static-web-deploy-local < all (0 seconds) [exec] [Wed, 21 Jul 2010 15:58:06 -0400] wcbd-deploy < static.web.deploy (0 seconds)To use the logger, provide the following options when calling the wcbd-ant.bat or wcbd-ant command to run the server deployment process:
-logger com.ibm.commerce.wcbd.ant.logger.PerformanceLogger
Note
that Ant does not capture the verbose, debug nor logger output in
the log file normally generated by the server deployment process.
The additional output will only be displayed in the console, so the
standard output and error streams should be redirected to a separate
log file when running the server deployment process with these logging
and tracing options. This can be done by appending the following options
when calling the wcbd-ant.bat
or wcbd-ant
command
to run the server deployment process, where log-file is
the log file to which the console output is written:
> log-file 2>&1