Advanced server deployment features
The WebSphere Commerce 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 WebSphere Commerce 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
behavior, 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 WebSphere Commerce Build and Deployment tool provides a means to map EJB references and resource references to EJB files 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 WebSphere Commerce 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, 28 Oct 2015 15:58:06 -0400] wcbd-deploy > static.web.deploy [exec] [exec] static.web.deploy: [exec] [echoNL] Deploying web server assets with C:\IBM\WCDE_ENT80\wcbd\deploy-server-workspace\wcbd-deploy-server-empty/static-web-deploy-local.xml. [exec] [Wed, 28 Oct 2015 15:58:06 -0400] static-web-deploy-local > all [exec] [exec] all: [exec] [copy] Copying 3 files to C:\web-server-root [exec] [Wed, 28 Oct 2015 15:58:06 -0400] static-web-deploy-local < all (0 seconds) [exec] [Wed, 28 Oct 2015 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