Skip navigation.
Downloads | Product Documentation | Support

Deployment Guide

# Deployment Tasks

You can easily deploy Liquid Data into new or existing domain using the WebLogic Configuration Wizard. On Windows you can access the WebLogic Configuration Wizard from the Start menu:

>     Start —> BEA WebLogic Platform 8.1 —> Configuration Wizard

Alternatively, you can access the WebLogic Configuration Wizard directly.

Windows:

>     <wl_home>\common\bin\config.cmd

UNIX:

>     <wl_home>/common/bin/config.sh

When deploying a Liquid Data-enabled domain through the WebLogic Configuration Wizard, deployment of Liquid Data components is automated. This includes distributing contents of the `LDS.ear` file to the appropriate server. (In a multi-module deployment the `ldconsole.jar` should only be deployed on the Administration Server; all other modules should only deployed on Managed Servers. See Deployable Liquid Data Components for details.)

When you start the WebLogic Configuration Wizard, you are first asked whether you want to create a new WebLogic platform domain or extend an existing domain. If you choose to import into an existing domain, you will be able to navigate to the domain you wish to extend and set deployment configurations appropriately.

This chapter describes tasks involved in deploying BEA Liquid Data for WebLogic. In addition to deploying Liquid Data to new and existing domains, some special cases are described in detail. The following sections are included:

- Deploying Liquid Data with a New WebLogic Domain
- Extending Liquid Data to an Existing WebLogic Domain
- Modifying the Startup Script To Set the Administrative User Name
- Copying a Liquid Data Configuration From Server to Server
- Configuring Remote Start for a Liquid Data-Enabled Managed Server
- Modifying the Windows Service Startup Script to Support Liquid Data

# Deploying Liquid Data with a New WebLogic Domain

When Liquid Data is installed, it adds several configuration templates to the WebLogic Configuration Wizard.

Figure 3-1 Liquid Data Options in WebLogic Platform Configuration Wizard

The Domain Configuration Wizard supports creation of the following Liquid Data-enabled domains:

- Basic Liquid Data and WebLogic Platform Domain
- Basic Liquid Data and WebLogic Integration Domain
- Basic Liquid Data and WebLogic Portal Domain
- Basic Liquid Data and WebLogic Server Domain

When creating a new, Liquid Data-enabled domain, you have a choice between Express and Custom configuration. As the name implies, Express auto-selects most options to allow you to create a Liquid Data-enabled domain very quickly.

If you choose the Custom option, the WebLogic Configuration Wizard guides you through a series of dialog boxes that allow you to set or select:

- Managed servers, clusters, and machines options
- Database (JDBC) options
- Messaging options (such as stores, topics and queues)
- User and group permissions
- Windows Start menu options and entries
- Administration options
- Development or production mode
- a Java SDK

After using the WebLogic Configuration Wizard, follow these steps to complete the deployment process:

1. If you chose production mode when creating the domain, follow the steps described in Modifying the Startup Script To Set the Administrative User Name on page 3-11.
2. Start or restart WebLogic Server, logging in as the default user created at the time when the domain was generated.
3. If you are setting up a clustered deployment you need to decide how your managed servers will access a shared `ldrepository` directory.

- If the deployed Liquid Data repository seldom if ever changes, you can simply set the `ldrepository` directory structure in the Liquid Data node of the WebLogic Administration Console (Configuration —> General —> Repository Directory) to a specific location and then copy the `ldrepository` directory and its contents to the same exact location on each managed server.

For example of you had a cluster with two managed servers your `ldrepository` directory might be located at:

Managed Server No. 1:

- `/opt/prod/bea_81/user_domains/ld_domain/ldrepository`

Managed Server No. 2:

- `/opt/prod/bea_81/user_domains/ld_domain/ldrepository`

The advantage of this approach is that you will get better performance with a local repository on each machine.

- Alternatively, you can change the `ldrepository` directory path so that it points to a shared volume to which all Managed Servers have access. On Windows, for example, you would point to a shared network drive mapped to a specific drive letter (such as `R:\ldrepos`).

In both cases you set the Liquid Data repository path using the Liquid Data node of the WebLogic Administration Console as follows:

1. Start or restart the Administration Console, logging in as appropriate.
2. In the left pane, click on the Liquid Data node, then click the General tab. The default repository is located in the BEA_HOME/user_projects/platform_domain_name directory such as:

>     BEAHOME/user_projects/domains/workshop/ldrepository

On each Managed Server, you need to configure the repository location by mounting (UNIX NFS) or mapping (Windows) logical drives to point to the configured repository root on the Administration Server. The directory must be shared and mapped to a virtual disk name. The path must be identical to the value specified in the `ldrepository` root directory field on the General tab in the Liquid Data node.

- On UNIX, use NFS to mount the exported directory in the respective BEA_HOME/user_projects/platform_domain_name. Make a shortcut of the mapped drive in the managed domain and name it the same as that used in the administration server domain.
- On Windows, map to the drive using the exact same drive letter and path (such as `R:\ldrepos`).

4. Further configure or reconfigure data sources, security, the repository, and other Liquid Data server settings, as needed, through WebLogic Administration Console, as described in the Liquid Data Administration Guide.
5. If you plan on running the domain as a Windows Service, modify the service startup script as described in Modifying the Windows Service Startup Script to Support Liquid Data on page 3-16.

For detailed information on using the WebLogic Configuration Wizard as well as deployment concepts see Overview of WebLogic Platform Configuration in Configuring WebLogic Platform. Also see WebLogic Configuration Wizard on-line help.

# Extending Liquid Data to an Existing WebLogic Domain

You can also use the WebLogic Configuration Wizard to import a Liquid Data configuration template into an existing WebLogic Platform domain.

Note: You cannot use the WebLogic Configuration Wizard to extend a clustered domain for Liquid Data + Samples.

Figure 3-2 Dialog Box Used to Extend an Existing Domain Configuration to Support Liquid Data

After you have extended a domain, the domain's `startWebLogic.cmd` script needs some minor editing. If you are extending a domain that includes WebLogic Workshop data from two versions of a workshop.properties file may need to be merged. Details are provided in Required Changes to Server Files.

Here are the general steps required to extend an existing WebLogic Server domain:

1. Start the WebLogic Configuration Wizard and select the Extend an Existing WebLogic Domain option.
2. Use the WebLogic Configuration Wizard directory browser to locate the domain (in this case the domain is named `workshop`, see Figure 3-3) you wish to extend. Then click Next.
3. There are two ways to extend a domain for Liquid Data: with or without the Liquid Data sample domain included. Once you have checked the extension you want, click Next.

Figure 3-3 Selecting a Domain in the WebLogic Configuration Wizard

When extending a domain, you can accept default settings or customize the domain. Customization includes:

- Database (JDBC) options
- Messaging (JMS) options such as stores, topics, and queries
- Identifying target servers and clusters onto which applications, JMS component services, JDBC component services, and other services are deployed. (In a multi-module deployment the `ldconsole.jar` is only deployed on the Administration Server; all other modules are deployed on Managed Servers. See Deployable Liquid Data Components for details.)
- Establishing application security, users, and groups

For detailed information on using the WebLogic Configuration Wizard as well as deployment concepts see Overview of WebLogic Platform Configuration in Configuring WebLogic Platform. See also WebLogic Configuration Wizard on-line Help.

Configure or reconfigure data sources, security, the repository, and other Liquid Data server settings, as needed, through WebLogic Administration Console, as described in the Liquid Data Administration Guide.

4. Edit command script files to support Liquid Data.

The following table shows Liquid Data-enabled deployment options and identifies scripts that need to be changed for the particular option.

Figure 3-4 Command Files Requiring Editing When Extending a Domain for Liquid Data or Liquid Data + WebLogic Application Integration (WLAI)

Operating System | Process | Liquid Data Extension
--- | --- | ---
Windows | Start WebLogic | Start Administration Server `startWebLogic.cmd` Start Managed Server `startManagedWebLogic.cmd` Workshop Properties, if present `workshop.properties`
UNIX | Start WebLogic | Start Administration Server `startWebLogic.sh` Start Managed Server `startManagedWebLogic.sh` Workshop Properties, if present `workshop.properties`

For example, if you have an existing WebLogic Workshop 8.1 domain and want to import a Liquid Data template, you would:

1. Run the WebLogic Configuration Wizard and extend the WebLogic Workshop domain for the Liquid Data option.
2. Modify the following command file:

`startWebLogic.cmd` (if an Administration Server) or `startManagedWebLogic.cmd` (if a Managed Server)

3. Start or restart the server(s).

5. If you are extending a clustered deployment you need to decide how your managed servers will access a shared `ldrepository` directory.

- If the deployed Liquid Data repository seldom if ever changes, you can simply set the `ldrepository` directory structure in the Liquid Data node of the WebLogic Administration Console (Configuration —> General —> Repository Directory) to a specific location and then copy the `ldrepository` directory and its contents to the same exact location on each managed server.

For example of you had a cluster with two managed servers your `ldrepository` directory might be located at:

Managed Server No. 1:

- `/opt/prod/bea_81/user_domains/ld_domain/ldrepository`

Managed Server No. 2:

- `/opt/prod/bea_81/user_domains/ld_domain/ldrepository`

The advantage of this approach is that you will get better performance with a local repository on each machine.

- Alternatively, you can change the `ldrepository` directory path so that it points to a shared volume to which all Managed Servers have access. On Windows, for example, you would point to a shared network drive mapped to a specific drive letter (such as `R:\ldrepos`).

In both cases you set the Liquid Data repository path using the Liquid Data node of the WebLogic Administration Console as follows:

1. Start or restart the Administration Console, logging in as appropriate.
2. In the left pane, click on the Liquid Data node, then click the General tab. The default repository is located in the BEA_HOME/user_projects/platform_domain_name directory such as:

>     BEAHOME/user_projects/domains/workshop/ldrepository

On each Managed Server, you need to configure the repository location by mounting (UNIX NFS) or mapping (Windows) logical drives to point to the configured repository root on the Administration Server. The directory must be shared and mapped to a virtual disk name. The path must be identical to the value specified in the `ldrepository` root directory field on the General tab in the Liquid Data node.

- On UNIX, use NFS to mount the exported directory in the respective BEA_HOME/user_projects/platform_domain_name. Make a shortcut of the mapped drive in the managed domain and name it the same as that used in the administration server domain.
- On Windows, map to the drive using the exact same drive letter and path (such as `R:\ldrepos`).

6. Further configure or reconfigure data sources, security, the repository, and other Liquid Data server settings, as needed, through WebLogic Administration Console, as described in the Liquid Data Administration Guide.
7. If you plan on running the domain as a Windows Service, modify the service startup script as described in Modifying the Windows Service Startup Script to Support Liquid Data on page 3-16.

## Required Changes to Server Files

WebLogic Platform Servers are started by command scripts. These scripts have either `cmd` (Windows) or `sh` (UNIX) extensions. You need to make some minor editing changes to these scripts when deploying Liquid Data into an existing domain.

- Administration Servers are started by `startWebLogic` scripts
- Managed Servers are activated by `startManagedWebLogic` scripts

Changes required to server command scripts are described in the following sections:

- Changes to Domain Command Scripts Enabled for Liquid Data

- Changes to Windows Start WebLogic Scripts
- Changes to UNIX Start WebLogic Scripts

Note: Command files are located in the root directory of the your extended domain and contain the following "readme" file:

`LiquidData.ld-extension-changes.readme`

Note: Generated command files may vary somewhat from examples shown.

#### Changes to Domain Command Scripts Enabled for Liquid Data

This section describes changes needed in Windows or UNIX command script files to support domains extended to support Liquid Data but not WebLogic Application Integration.

### Changes to Windows Start WebLogic Scripts

Edit `startWebLogic.cmd`, using these steps:

1. Add the following command lines after WL_HOME is defined:

>     set LD_HOME=%WL_HOME%\<LD_HOME>
>     call %LD_HOME%\setenv.cmd

where <LD_HOME> is the root Liquid Data directory.

Example:

>     set WL_HOME=D:\bea\weblogic81
>     set LD_HOME=%WL_HOME%\liquiddata
>     call %LD_HOME%\setenv.cmd

2. Add the following command to the class path:

>     %LDCOMMONCP%

Example:

>     @rem Call WebLogic Server
>     set CLASSPATH=%WEBLOGIC_CLASSPATH%;%POINTBASE_CLASSPATH%;%JAVA_HOME%\jre\lib\rt.jar;%WL_HOME%\server\lib\webservices.jar;%CLASSPATH%;%LDCOMMONCP%

>     Changes to UNIX Start WebLogic Scripts

Edit the `startWebLogic.sh` file.

1. Add the following command lines after WL_HOME is defined:

>     LD_HOME=$WL_HOME/<LD_HOME>
>     .$LD_HOME%/setEnv.sh

where <LD_HOME> is the root Liquid Data directory.

Example:

>     WL_HOME=/bea/weblogic81

>     LD_HOME=$WL_HOME/liquiddata
>     . "$LD_HOME/setEnv.sh"

2. Insert the following line immediately before the startweblogic server command (and after other CLASSPATH definitions):

>     CLASSPATH=$CLASSPATH:$LDCOMMONCP

Example:

>     # Start WebLogic server

>     CLASSPATH="${WEBLOGIC_CLASSPATH}${CLASSPATHSEP}${POINTBASE_CLASSPATH}${CLASSPATHSEP}${JAVA_HOME}/jre/lib/rt.jar${CLASSPATHSEP}${WL_HOME}/server/lib/webservices.jar${CLASSPATHSEP}${CLASSPATH}"

>     export CLASSPATH

>     CLASSPATH=$CLASSPATH;$LDCOMMONCP
>     # supports Liquid Data extension

>     "$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS}

### Changes to the workshop.properties file

After the Liquid Data extension is imported into a domain, it will add a file called `workshop.properties` into the domain. If a `workshop.properties` file existed before the Liquid Data extension was imported, the old file will be automatically backed up by the WebLogic Configuration Wizard to the filename `workshop.properties.bak`

If you find such a file in the root directory of the server you are extending, you need to merge that file with the new `workshop.properties` file. The order of the files being merged does not matter.

# Modifying the Startup Script To Set the Administrative User Name

If you use the Domain Configuration Wizard to create a Liquid Data production domain, or if you have a domain that does not contain the `boot.properties` file at the root level, you must modify the startup script to specify the name of an administrative user (a user who is a member of the WebLogic `Administrators` group). If the domain does not have the administrative username set, an error will occur on server startup.

The startup script for Liquid Data domains created with the Domain Configuration Wizard contains the following code fragment:

>     if "%WLS_PRODUCTION_MODE%"=="true" (
>     	set JAVA_OPTIONS=%JAVA_OPTIONS% -Dcom.bea.ld.adminusername=
>     	)

Note: In order for the startup script to correctly run, an administrator's user name must be supplied.

Perform the following steps to update the startup scripts for production domains or domains that do not have a `boot.properties` file:

1. Open the startup script for your domain in a text editor. The startup script is in the root level of the domain and is named `startWebLogic.cmd` for Windows systems and `startWebLogic.sh` for UNIX systems.
2. Find the lines shown above in the startup script.
3. Enter the name of a user who is a member of the Administrators group following the terminating equals (`=`) sign. For example, if an administrative user is named `system_admin`, change:

>     JAVA_OPTIONS="%JAVA_OPTIONS% -Dcom.bea.ld.adminusername=system_admin"

to the following (emphasis added):

>     JAVA_OPTIONS="%JAVA_OPTIONS% -Dcom.bea.ld.adminusername=system_admin"

1. Save the file.
2. Start the domain.

# Copying a Liquid Data Configuration From Server to Server

There are two ways to copy a Liquid Data server configuration information from one server to another, such as from a development environment to a production environment.

1. You can use the WebLogic Configuration Template Builder to create a domain template and then use the WebLogic Configuration Wizard to deploy it. To do this some detailed understanding of the composition of a domain is needed.

You can access the Configuration Template Builder from the following locations:

Windows:

>     <wl_home>\common\bin\config_builder.cmd

UNIX:

>     <wl_home>/common/bin/config_builder.sh

For more information see Creating Configuration Templates Using the Weblogic Configuration Template Builder.

1. You can also can transfer settings already configured in the development environment.

The following illustration shows the Liquid Data components that you need to transfer to the production server:

Figure 3-5 Migrating From a Development to a Production Server

To migrate from a development environment to a production environment, you need to migrate the following configuration information:

Table 3-6 Liquid Data Configuration Information that Can Be Migrated

Item | Description
--- | ---
`config.xml` file | Contains the WebLogic Server configuration, including the domain configuration and, if applicable, the JDBC database configuration. Open the `config.xml` file on the target server and edit any machine-specific parameters.
startup script (`startWebLogic.cmd` or `startWebLogic.sh`) | Contains the Liquid Data server startup script. Open the startup script on the target server and edit any machine-specific parameters. Also, for a production environment, change the `STARTMODE` variable to `true`.
`configMap.xml` and `webapp.template` files | Copy these files from `<WL_HOME>/<LIQUIDDATA>/server/lib` on the source server to the corresponding directory on the target server. (Not necessary if the target server already has Liquid Data enabled.)
security realm | Replicate the security realm configuration on the production server. The Liquid Data security configuration includes groups, users, and roles. How you copy the configuration depends on the type of compatibility security realm that you have set up according to the instructions in "Defining a Compatibility Security Realm" in Implementing Security in the Liquid Data Administration Guide. (Not necessary if the target server already has Liquid Data enabled.)
server repository | On the development server, create a compressed image of the complete server repository, including all sub-folders, using a TAR or ZIP file for the Unix and Windows platforms, respectively. Copy this compressed file to the production server and expand it. On the production server, start the WebLogic Administration Console and configure the repository root directory to be the directory where the source repository was unzipped to.
Liquid Data configuration settings | On the development server, export the Liquid Data configuration information to an export file. On the production server, import the contents of the export file. For instructions, see Importing and Exporting Liquid Data Configurations in the Liquid Data Administration Guide.
Web services and other live applications | If there are any "live" applications in the development server such as an .`EAR` file for a web service, you should move a copy of the file into the application directory after the target server is up and running. This needs to be done before changing the Start mode to True.

# Configuring Remote Start for a Liquid Data-Enabled Managed Server

If you create a clustered Liquid Data domain or extend an existing clustered domain to support Liquid Data and you want to be able to remotely start your managed server(s) from the WebLogic Administration Console, you will need to insert instructions copied from the Administration Server's executed startWebLogic script to each Managed Server's configuration instructions.

You can use the following steps to accomplish this for each Managed Server in your cluster:

1. Start your Administration Server using the startWebLogic command script. For example:

>     <user_domain>/<domain>/startWebLogic.cmd

>     where user_domain>/<domain> is the root directory of your WebLogic domain (for example, d:\user_domains\mydomain).

As you are copying sections of the executed script you may find it easiest to create a text file containing the output of the startWebLogic process. On Windows you can create such a file using:

>     startWebLogic >> scriptoutput.txt

2. Edit the output, concatenating the line beginning `CLASSPATH=` with the line beginning `PATH=`
3. Copy the resulting string (without any return codes) into the Class Path field in WebLogic Administration Console Configuration —> Remote Start page. This override the default startup classpath of your managed server.
4. Copy the arguments used in starting your server into the Arguments field in WebLogic Administration Console Configuration —> Remote Start page.

The server startup line would being with something similar to:

>     Starting WLS with line:
>     d:\b11\JDK142\bin\java <server arguments>

and the arguments to be copied into the field would include everything following the invocation:`java`

This override the default startup arguments for your Managed Server.

5. Start your Node Manager, located at `<`BEA_HOME`>/server/bin`

For example:

>     d:\bea_81_sp3\weblogic81\server\bin\startNodeManager.cmd

6. Test the results by starting or restarting each Managed Server.

You can locate your server by name under the Servers section of your domain in the WebLogic Administration Console. Once selected, you can use the Control tab to start or restart your Managed Server.

See Overview of Node Manager at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/adminguide/nodemgr.html for additional information.

# Modifying the Windows Service Startup Script to Support Liquid Data

If you create a Liquid Data domain and want to run it as a Windows Service, you must modify the startup script for the Window Service to include needed Liquid Data resources in the classpath.

If you have created your domain in the WebLogic Configuration Wizard and selected the Run as a Service option, then a file named `installService.cmd` will be in your domain directory. You will need to edit that file.

Alternatively you can create a script which invokes the Windows service command file located in `<WL_HOME>/server/bin` directory. If that is how your will start your Windows service then you will need to edit the `installSvc.cmd` file located in that directory.

The editing instructions for `installSvc.cmd` or `installService.cmd` are the same.

1. Open the appropriate file in a text editor to add Liquid Data resources to the classpath.

- If you selected the Run as a Service option in the Configuration Wizard when you created the domain open:

>     <user_domain>/<domain>/installSvc.cmd

where user_domain>/<domain> is the root directory of your WebLogic domain (for example, `d:\user_domains\mydomain`).

- Otherwise open:

>     <WL_HOME>/server/bin/installService.cmd

where WL_HOME is the directory in which WebLogic is installed (for example, `d:\bea\weblogic81`).

2. Modify the file by changing the line setting the class path from:

>     set CLASSPATH=%WEBLOGIC_CLASSPATH%;%CLASSPATH%

to:

>     call "%WL_HOME%\liquiddata\setenv.cmd
>     set CLASSPATH=%WEBLOGIC_CLASSPATH%;%CLASSPATH%;%LDCOMMONCP%

1. Locate the following code in the file:

>     if "%PRODUCTION_MODE%"=="true" (
>     	set JAVA_OPTIONS=%JAVA_OPTIONS% -Dcom.bea.ld.adminusername=
>     	)

In order for the startup script to correctly run, an administrator's user name must be supplied.

1. Enter the name of a user who is a member of the Administrators group following the terminating equals (`=`) sign. For example, if an administrative user is named `system_admin`, change:

>     JAVA_OPTIONS="%JAVA_OPTIONS% -Dcom.bea.ld.adminusername=system_admin"

to the following (emphasis added):

>     JAVA_OPTIONS="%JAVA_OPTIONS% -Dcom.bea.ld.adminusername=system_admin"

1. Save your file (either `installSvc.cmd` or `installService.cmd`).
2. Perform the steps in the WebLogic Server documentation for running WebLogic Server as a Windows Service:

http://download.oracle.com/docs/cd/E13222_01/wls/docs81/adminguide/winservice.html

3. Startup and test the domain running as a Windows Service.