Personal tools

Views

LiveCycle Data Services:Installation Instructions

From Adobe Labs

Table of contents
1 Installing LiveCycle Data Services 2.6 Beta 2

1.1 LiveCycle Data Services ES with integrated Apache Tomcat application server

1.1.1 Running the TestDrive with the integrated Tomcat installation

1.2 LiveCycle Data Services ES J2EE web applications
1.3 Additional server-specific configuration

1.3.1 Tomcat

1.3.1.1 Configuring ActiveMQ 4.1.1 with Tomcat 6.0.x

1.3.2 WebSphere
1.3.3 JBoss

1.3.3.1 OC4J

1.3.4 Running from a compressed WAR

Installing LiveCycle Data Services 2.6 Beta 2

Adobe LiveCycle Data Services ES runs as a J2EE web application. Each installer allows you to choose from the following configurations:

LiveCycle Data Services ES offers installers for the following platforms:

LiveCycle Data Services ES supports the following application servers:

Note that LiveCycle Data Services ES does not include any Flex compilers. This includes the web tier compiler included in previous releases. For information about setting your compilation environment, see Setting up an SDK, compilers, and Flex Builder for LiveCycle Data Services ES 2.6. Also note that you can integrate the stand-alone LiveCycle Data Services ES server with ColdFusion. For more information, see Integrating LiveCycle Data Services ES with ColdFusion 8.

These installation instructions refer to the root directory where you installed LiveCycle Data Services ES as install_root.

The installers include the following Web Application Archive (WAR) files:

Each WAR file is a separate, stand-alone web application. If you are using the J2EE web applications configuration, you must have an existing J2EE application server or servlet container available and understand web application deployment. If you do not have an existing J2EE server or are not familiar with WAR file deployment, use the integrated Tomcat configuration to get started.

LiveCycle Data Services ES with integrated Apache Tomcat application server

The LiveCycle Data Services ES with integrated Tomcat installation option contains the following files and directories under the installation root:

readme.htm Contains overview information.
lcds.war LiveCycle Data Services ES web application template, used as a starting point for new applications.
lcds-samples.war LiveCycle Data Services ES sample applications.
ds-console.war Simple monitoring application for LiveCycle Data Services ES deployments.
license.txt license information.
/tomcat Contains an installation of Apache Tomcat that includes lcds, lcds-samples, and console web applications expanded and deployed in the default server.
/resources Contains Flex SDK source code, fully commented configuration files, as well as directories and files used for security, clustering, Flex Ajax Bridge, and WSRP. Flash Player installers are in the flex_sdk_3.zip file.

To install LiveCycle Data Services ES in the integrated Tomcat configuration:

  1. Read the LiveCycle Data Services ES release notes for known issues and any late-breaking information.
  2. Start the installation program. Do one of the following, depending on your operating system:

    • Windows - Double-click the installer file (lcds26-win.exe).
    • UNIX or Linux - Set the working directory to the directory that contains the installer file, and then enter the following command specifying the installer file for your operating system; for example: 
      ./lcds26-lin.bin -i console
  3. Accept the license agreement.
  4. On the Serial Number screen, leave the serial number field blank and click Next.
  5. Specify the directory in which to install LiveCycle Data Services ES or accept the default location.
  6. Select the LiveCycle Data Services With Tomcat option.
  7. Complete the remaining installer steps.
  8. To start LiveCycle Data Services ES, open a command window, navigate to install_root/tomcat/bin, and enter the catalina start command. On UNIX and Linux, enter ./catalina start. Optionally, on Windows you can navigate to the install_root/tomcat/bin in Windows Explorer and double-click the catalina.bat icon.
  9. The LiveCycle Data Services ES sample applications use an HSQLDB database that is installed in the install_root/sampledb directory. To start the sample database:
    • Open a command prompt and go to the install_root/sampledb directory.
    • Run startdb.bat (Windows) or startdb.sh (Unix-based systems).

Running the TestDrive with the integrated Tomcat installation

In addition to the LiveCycle Data Services ES WAR files, the LiveCycle Data Services ES installers provide an option to install a version of Tomcat (6.0.14) with a set of web applications fully configured with LiveCycle Data Services ES (including lcds-samples). To run the test drive after installing the integrated Tomcat configuration:

  1. Start Tomcat (startup.bat or startup.sh in /lcds/tomcat/bin)
  2. Open a browser and access the samples home page:
    http://localhost:8400/lcds-samples
  3. Take the test drive!

LiveCycle Data Services ES J2EE web applications

The LiveCycle Data Services ES J2EE web application configuration option installs the following files and directories under the installation root:

readme.htm Contains overview information.
lcds.war LiveCycle Data Services ES web application, used as a starting point for new applications.
lcds-samples.war LiveCycle Data Services ES sample applications.
ds-console.war Simple monitoring application for LiveCycle Data Services ES deployments.
license.txt license information.
/resources Contains Flex SDK source code, fully commented configuration files, as well as directories and files used for security, clustering, Flex Ajax Bridge, and WSRP. Flash Player installers are in the flex_sdk_3.zip file.

To install LiveCycle Data Services ES web applications:

  1. Read the LiveCycle Data Services ES release notes for known issues and any late-breaking information.
  2. Start the installation program. Do one of the following, depending on your operating system:

    • Windows - Double-click the installer file (lcds26-win.exe).
    • UNIX or Linux - Set the working directory to the directory that contains the installer file, and then enter the following command specifying the installer file for your operating system; for example: 
      ./lcds26-lin.bin -i console
  3. Accept the license agreement.
  4. On the Serial Number screen, leave the serial number field blank and click Next.
  5. Specify the directory in which to install LiveCycle Data Services ES or accept the default location.
  6. Select the LiveCycle Data Services J2EE web application option.
  7. Complete the remaining installer steps.
  8. Deploy the lcds, lcds-samples, and ds-console web applications by using your application-server-specific deployment method. For example, for Tomcat, copy the WAR files to the webapps directory and restart the server.
  9. The LiveCycle Data Services ES sample applications use an HSQLDB database that is installed in the install_root/sampledb directory. To start the sample database:
    • Open a command prompt and go to the install_root/sampledb directory.
    • Run startdb.bat (Windows) or startdb.sh (Unix-based systems).
  10. Perform additional application-server specific configuration, as described in Additional server-specific configuration .

To install LiveCycle Data Services ES as J2EE web application by using the Java installer (any platform):

  1. Read the LiveCycle Data Services ES release notes for system requirements and any late-breaking information.
  2. Run the installer by opening a command prompt, navigating to the directory that contains the downloaded JAR file (lcds26-install.jar), and executing the following command: 
    java_home/bin/java -jar lcds26-install.jar -i console
  3. Continue with steps 3 through 9 of To install LiveCycle Data Services ES web applications.

Additional server-specific configuration

You may need to perform additional configuration steps for your application server:

Tomcat

To use LiveCycle Data Services ES with Tomcat when not using the integrated Tomcat configuration, you should install support for the Java Transaction API (JTA) and may also need to install several other libraries depending on the features that you plan to use. Follow these steps after deploying the LiveCycle Data Services WAR files. These steps are not necessary for the integrated Tomcat installation.

  1. Stop Tomcat.
  2. To install support for JTA, a recommended implementation is the Java Open Transaction Manager (JOTM), which is a fully functional open source stand-alone transaction manager.
    1. Download JOTM from http://jotm.objectweb.org/.
    2. Copy the JAR files from jotm-root/lib to [tomcat-root]/common/lib.
    3. Create a context file for your web application and register JOTM using the Transaction element, e.g. for the samples WAR create a tomcat-root/conf/Catalina/localhost/samples.xml file and add the following lines: 
      <Context docBase="${catalina.home}/webapps/samples" privileged="true"
   antiResourceLocking="false" antiJARLocking="false">
   <Transaction factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60"/>
</Context>

      Note: If a context file already exists for your web application, simply add the <Transaction> element under the <Context> element. 

      4.
  3. Increase the maximum memory to at least 512MB. This is achieved by specifying the maximum heap size for the JVM in the JAVA_OPTS variable: -Xmx512m
  4. (Optional) To enable custom authentication, locate the Tomcat security resource libraries under install_root/resources/security/tomcat.
    1. Place flex-tomcat-common.jar in tomcat/lib/blazeds.
    2. Place flex-tomcat-server.jar in tomcat/lib/blazeds.
    3. Edit the catalina.properties file which can be found in the tomcat/conf directory. Find the common.loader property and add the following path to the end of the list: ${catalina.home}/lib/blazeds/*.jar
    4. Add <Valve className="flex.messaging.security.TomcatValve"/> tag to the Context descriptors. For example, for the LiveCycle Data Services ES samples WAR: 
      <Context path="/lcds-samples"
 docBase="${catalina.home}/webapps/lcds-samples" debug="0">
  <Valve className="flex.messaging.security.TomcatValve"/>
</Context>

      You will now be authenticated against the current Tomcat realm. Usually, the default for this authentication stores user information in conf/tomcat-users.xml. See the Tomcat documentation for more information on realms. See the documentation for more information on LiveCycle Data Services ES custom authentication.

    5. You may also need to update the active <login-command> in /WEB-INF/flex/services-config.xml in each deployment of a LiveCycle Data Services ES WAR file. For Tomcat, ensure that the TomcatLoginCommand is active in the <security> section: 
      <security>
<login-command
 class="flex.messaging.security.TomcatLoginCommand"
 server="Tomcat"/>
...
      6.
  5. (Optional) To use the JMSAdapter with the Message Service, you must install and configure a JMS provider (such as ActiveMQ or openJMS) for use with Tomcat.
  6. Restart Tomcat.

Configuring ActiveMQ 4.1.1 with Tomcat 6.0.x

These instructions create a configuration that matches what is distributed with LiveCycle Data Services ES. You should be able to integrate Apache ActiveMQ 4.1.1 with earlier versions of Tomcat and you should also be able to integrate newer versions of ActiveMQ with Tomcat 6.0.x, but none of these configurations have been tested. These instructions require that you have a valid Apache Ant installation.

Complete the following steps to integrate ActiveMQ with your own installation of Tomcat 6.0.x:
  • Download ActiveMQ 4.1.1 from http://activemq.apache.org.
  • Download and install the ActiveMQ distribution following the instructions provided on the ActiveMQ website.
  • ActiveMQ ships with an example that contains the JAR files and configuration settings that work with a web application deployment. Build the example by opening a command prompt, changing to the activemq_root/example directory and running the following command to build the example: 
    • ant war
  • In the tomcat_root/lib directory, create a new directory called activemq4.1.1. Copy the contents of the activemq_root/example/target/activemq-web/WEB-INF/lib directory to this new directory.
  • Open the catalina.properties file from the tomcat_install/conf directory in a text editor. Modify the common.loader property by adding the following to the list of comma-seperated paths: 
    ${catalina.home}/lib/activemq4.1.1/*.jar
  • Modify your LiveCycle Data Services ES web application to start an ActiveMQ message broker when the web application starts. To do this, open the WEB-INF/web.xml file for your web application in a text editor. Add the following context-param and listener elements. Make sure you put them in the correct location within the web.xml. The order of these must match the web-app dtd.
    • <context-param>
    <param-name>brokerURI</param-name>

    <param-value>/WEB-INF/activemq.xml</param-value>
</context-param>

<listener>
    <listener-class>org.apache.activemq.web.SpringBrokerContextListener</listener-class>
</listener>
  • In the WEB-INF directory of your web application create a new file called activemq.xml. Open the file in a text editor and add the following text: 
    • <?xml version="1.0" encoding="UTF-8"?>
<beans>
	<broker useJmx="true" persistent="false"
	xmlns="http://activemq.org/config/1.0" brokerName="myBroker">

		<transportConnectors>
			<transportConnector name="default"
			uri="tcp://localhost:61716"/>
		</transportConnectors>
	</broker>

</beans>

    This starts an ActiveMQ message broker with a broker name of myBroker listening for requests on the localhost network interface at port 61716.

  • Add the ActiveMQ connection factories and any JMS Topics and Queues you want to use to JNDI. The easiest way to do this in Tomcat 6.0.x is to create a context file for your web application and put the settings in there. To do this, create a new file in the tomcat_install/conf/Catalina/localhost directory. If the Catalina/localhost directory does not exit already create it now. The new file that you create should have the same name as the web application with a .xml extension. For example, if your LiveCycle Data Services ES web application is named samples the Tomcat context file should be named samples.xml. For more information on context files, refer to your Tomcat documentation. Once you have created the file, open it in a text editor. Add the following contents to the file, replacing the example topic and queue shown here with your own topics and queues:
    • <Context privileged="true" antiResourceLocking="false" antiJARLocking="false" reloadable="true">

    <Resource name="jms/flex/TopicConnectionFactory"
                type="org.apache.activemq.ActiveMQConnectionFactory"
                description="JMS Connection Factory"
                factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                brokerURL="tcp://localhost:61716"

                brokerName="myBroker"/>
 	<Resource name="jms/topic/flex/simpletopic"
                type="org.apache.activemq.command.ActiveMQTopic"
                description="my Topic"

                factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                physicalName="FlexTopic"/>
	<Resource name="jms/flex/QueueConnectionFactory"
                type="org.apache.activemq.ActiveMQConnectionFactory"

                description="JMS Connection Factory"
                factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                brokerURL="tcp://localhost:61716"
                brokerName="myBroker"/>

    <Resource name="jms/queue/flex/simplequeue"
                type="org.apache.activemq.command.ActiveMQQueue"
                description="my Queue"
                factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                physicalName="FlexQueue"/>                
    <Valve className="flex.messaging.security.TomcatValve"/>

</Context>
  • Start your Tomcat server. The ActiveMQ message broker should start listening for messages on port 61716 and you should be able to send messages to and receive message from the JMS topics and queues you have configured. For more information about configuring and using ActiveMQ, please refer to the ActiveMQ documentation which is available on http://activemq.apache.org.

    • WebSphere

    LiveCycle Data Services ES includes a WebSphere-specific implementation of RTMP server. This version uses threads created by WebSphere.

    To configure LiveCycle Data Services ES for use with WebSphere:

    1. Expand a LiveCycle Data Services ES WAR file to a temporary folder: 
      jar -xvf lcds.war
    2. Uncomment the resource-ref element for WorkManager in the web.xml file. This makes the resource available in java:comp/env/ at res-ref-name (java:comp/env/wm/MessagingWorkManager): 
      <resource-ref>
       <description>Flex Messaging WorkManager</description>
       <res-ref-name>wm/MessagingWorkManager</res-ref-name>
       <res-type>com.ibm.websphere.asynchbeans.WorkManager</res-type> 
      <res-auth>Container</res-auth>
       <res-sharing-scope>Shareable</res-sharing-scope>
   </resource-ref>
    3. Map the WorkManager resource-ref in the web.xml file to the RTMPEndpoint in lcds-webapp-root/WEB-INF/flex/services-config.xml. The websphere-workmanager-jndi-name maps to the res-ref-name available in java:comp/env in step 2. For example: 
      <channel-definition id="my-rtmp" class="mx.messaging.channels.RTMPChannel">
   <endpoint url="http://{server.name}:2038/"
    class="flex.messaging.endpoints.RTMPEndpoint"/>
       <properties>
         ...         
         <websphere-workmanager-jndi-name>
           java:comp/env/wm/MessagingWorkManager
         </websphere-workmanager-jndi-name>
         ...
       </properties>
</channel-definition>
    4. To configure data service destinations that do not use transactions with RTMP based channels, set <use-transactions>false</use-transactions> for the data service destination in the /WEB-INF/flex/data-management-config.xml file.
    5. To integrate the new NIO HTTP server, update the services-config.xml to include the websphere-workmanager-jndi-name declaration in the <servers> section: 
      <servers><br />  <server class="flex.messaging.socketserver.SocketServer"
    id="data-nio-server">
    <properties><br />     <bind-port>12080</bind-port>
     <websphere-workmanager-jndi-name>
       java:comp/env/wm/MessagingWorkManager
     </websphere-workmanager-jndi-name>
    </properties>
  </server>
  <server class="flex.messaging.socketserver.SocketServer"
    id="data-nio-secure-server">
    <properties>
     <bind-port>2051</bind-port>
     <websphere-workmanager-jndi-name>
       java:comp/env/wm/MessagingWorkManager
     </websphere-workmanager-jndi-name>
     <keystore-password>changeit</keystore-password>
    </properties>
  </server>
</servers>
    6. In lcds-webapp-root/WEB-INF/flex/services-config.xml, create a server ref in your channel definitions that use the NIO server. For example: 
      7. <channel-definition
   class="mx.messaging.channels.AMFChannel" id="perf-nio-amf">
  <endpoint class="flex.messaging.endpoints.NIOAMFEndpoint"
    url="http://{server.name}:12080/nioamf">
  </endpoint>
  <strong><server ref="data-nio-server"/></strong>
 ...
</channel-definition>
    7. Create a WAR file from the expanded directory structure. For example: 
      8. jar -cvf lcds.war *
    8. From the WebSphere Administrator, define a WorkManager for use by your application. From the admin, choose Resources > Asynchronous Beans > Work managers. By default, the DefaultWorkManager is available at the wm/default jndi-name. Also, you can add a separate WorkManager for your application.
    9. Deploy the WAR file. During deployment, map the WorkManager resource-ref to an actual JNDI name for your WorkManager. For the DefaultWorkManager, wm/MessagingWorkManager (name used by your web.xml) maps to wm/default (the JNDI name of the actual server resource).
    10. (Optional) To enable custom authentication, open the WebSphere Administrator and configure a custom user registry using the files under install_root/resources/security/websphere/ as usersFile and groupsFile custom properties.

    Running the administration console on WebSphere with administrative security enabled

    To run the administration console on WebSphere with administrative security enabled, complete the following steps:

    1. Uncomment the <security> section under the RuntimeManagement destination in the services-config.xml file for the console web application (the file has comments instructing users to do this when running on WebSphere with administrative security enabled).
    2. Uncomment the <security-constraint section under <security> in the services-config.xml file for the console web application (the file has comments instructing users to do this when running on WebSphere with administrative security enabled).
    3. Make sure you use the WebSphereLoginCommand.
    4. Create a WAS User Group called console_administrator and add any users who should be able to use this application to this group. These users must also have at least one role that allows them to access MBeans under WebSphere security.

    JBoss

    (Optional) To enable custom authentication, you must perform the following configuration steps:

    1. Put install_root/resources/security/tomcat/flex-tomcat-common.jar and install_root/resources/security/tomcat/flex-tomcat-server.jar in the jboss_root/server/default/lib folder.
    2. Add <Valve className="flex.messaging.security.TomcatValve"/> tag to the Context descriptors.
    3. Restart JBoss.

    This configuration provides authentication against the current JBoss realm. Usually, the default for this authentication stores user information in jboss_root/server/default/conf/users.properties and roles information in jboss_root/server/default/conf/roles.properties. For more information on realms, see the JBoss documentation. For more information on LiveCycle Data Services ES custom authentication, see the LiveCycle Data Services ES documentation and information in the install_root/resources/security directory.

    OC4J

    To run LiveCycle Data Services ES on Oracle Containers for J2EE (OC4J), you must pass make the following changes in the oc4j.cmd file:

    The following example shows CMDARGS and JVMARGS lines that use these arguments:

    set JVMARGS=%OC4J_JVM_ARGS%
  -Xmx512m -Doc4j.jmx.security.proxy.off=true
  set CMDARGS=-config "%SERVER_XML%" -userThreads

    Running from a compressed WAR

    To run LiveCycle Data Services ES from a compressed WAR file, perform the following steps:

    1. Expand the lcds.war file using winzip or the JAR utility.
    2. Create your application, including SWF files, ActionScript files, configuration settings and HTML wrappers.

      Note: For more information on compiling SWF files and creating HTML wrappers, see the Flex 3 documentation.

    3. Create a compressed WAR file from the expanded web application structure.
    4. Deploy the compressed WAR file.

      Note that many samples applications in lcds-samples.war will not function within a compressed web application. It is therefore advised to deploy the lcds-samples web application as an uncompressed war. If you uncompress a WAR file into a subdirectory you create, then that subdirectory must match the name of the prefix of the WAR file, which is also the context root of the web application.

    5. The LiveCycle Data Services ES sample applications use an HSQLDB database that is installed in the install_root/sampledb directory. To start the sample database:
      • Open a command prompt and go to the install_root/sampledb directory.
      • Run startdb.bat (Windows) or startdb.sh (Unix-based systems).

    Retrieved from "http://labs.adobe.com/wiki/index.php/LiveCycle_Data_Services:Installation_Instructions"