[BlazeDS] 설치 가이드 / Installation Guide

원문: http://opensource.adobe.com/wiki/display/blazeds/Installation+Guide

J2EE 웹 어플리케이션 에서 실행되는 BlazeDS 는 아래와 같은 설정이 포함된 ZIP 파일의 형태로 제공됩니다:

• Apache Tomcat 어플리케이션 서버와 통합된 BlazeDS
• BlazeDS 웹 어플리케이션

BlazeDS 는 아래의 플랫폼 위에서 동작합니다:

• Windows
• Linux
• Solaris

이 설치 가이드에서 install_root 은 BlazeDS ZIP 파일의 압축을 푼 디렉토리를 말합니다.

아래의 Web Application Archive (WAR) 파일이 BlazeDS 에 포함되어 있습니다:

• blazeds.war - 가장 중요한 BlazeDS WAR 파일: BlazeDS 어플리케이션을 만들기 위한 출발점으로 사용.
• samples.war - 샘플 BlazeDS 어플리케이션.
• ds-console.war - BlazeDS 배포를 위한 간단한 모니터링 어플리케이션.

각 WAR 파일은 별도의 독립적인 웹 어플리케이션입니다. J2EE 웹 어플리케이션 옵션을 사용한다면, J2EE 어플리케이션 서버 또는 서블릿 컨테이너와 웹 어플리케이션 배포에 대한 이해가 필요합니다. J2EE 서버가 없거나 WAR 파일 배포에 익숙하지 않다면, Tomcat 과 통합된 파일로 시작하십시오.

Apache Tomcat 어플리케이션 서버와 통합된 BlazeDS 설치 / application serverInstalling BlazeDS with integrated Apache Tomcat application server

BlazeDS with integrated Tomcat ZIP 파일의 압축을 푼 폴더에는 아래의 파일과 디렉토리가 있습니다:

• readme.htm - 중요한 정보에 대한 개괄.
• blazeds.war - 새로운 어플리케이션을 시작하는데 사용되는 BlazeDS 웹 어플리케이션.
• samples.war - BlazeDS 샘플 어플리케이션.
• ds-console.war - BlazeDS 배포를 위한 간단한 모니터링 어플리케이션.
• license.txt - 라이센스 정보.
• /tomcat - Contains an installation of Apache Tomcat that includes blazeds, 샘플, ds-console 웹 어플리케이션이 포함된 Apache Tomcat.
• /resources - 보안, 클러스터링, Flex-Ajax Bridge, 수동으로 생성하는 HTML wrapper 에서 사용되는 파일과 디렉토리, Flex SDK 소스 코드, 설정 파일. Flash Player 인스톨러는 Flex SDK ZIP 파일에 있습니다.

통합된 Tomcat 에 BlazeDS 설치 / To install BlazeDS in the integrated Tomcat configuration:

1. 알려진 이슈와 최신 정보가 담긴 BlazeDS 릴리즈 노트 를 읽으십시오. 
2. ZIP 파일의 압축을 푸세요.
3. BlazeDS 를 설치하려는 기계에 Java Development Kit (JDK) 이 설치되어 있고, JAVA_HOME 이란 환경 변수가 설정되어 있는지 확인하십시오.
4. 윈도우에서 BlazeDS 를 시작하려면, 명령창을 열고 to install_root/tomcat/bin 로 이동하십시오. 그리고 catalina start 명령을 입력하십시오. OS X, UNIX, Linux 에서는 ./catalina start 를 입력하십시오. 윈도우에서는 윈도우 익스플로러를 사용하여 install_root/tomcat/bin 에 접근할 수 있고, startup.bat 아이콘을 더블클릭하여 실행할 수 있습니다.

Tomcat 이 통합된 설치에서 샘플 실행 / Running the Test Drive with the integrated Tomcat install

BlazeDS WAR 파일 외에, 다운로드 파일에는 BlazeDS 가 설정된 몇 개의 웹 어플리케이션이 포함된 6.0.14 버전의 Tomcat이 있습니다. Tomcat 이 통합된 설치를 다운 받아서 압축을 푼 후 샘플을 실행하려면:

1. Tomcat 시작 (/blazeds/tomcat/bin 에서 startup.bat 이나 startup.sh).
2. BlazeDS 샘플 어플리케이션은 install_root/sampledb 디렉토리에 설치된 HSQLDB 데이터베이스를 사용합니다. 샘플 데이터베이스를 시작하려면:
   • 명령창을 열어서 install_root/sampledb 디렉토리로 이동하십시오.
   • startdb.bat (Windows) 이나 startdb.sh (Unix 기반의 시스템)를 실행하십시오.
3. 브라우저를 열고 샘플 홈페이지에 접속하십시오:
   http://localhost:8400/samples/
4. 샘플을 실행해 보세요!

Installing BlazeDS with J2EE web applications

BlazeDS J2EE 웹 어플리케이션 옵션은 아래의 파일과 디렉토리를 설치합니다:

• readme.htm - 중요한 정보에 대한 개괄.
• blazeds.war - 새로운 어플리케이션을 시작하는데 사용되는 BlazeDS 웹 어플리케이션.
• samples.war - BlazeDS 샘플 어플리케이션.
• ds-console.war - BlazeDS 배포를 위한 간단한 모니터링 어플리케이션.
• license.txt - 라이센스 정보.
• /resources - 보안, 클러스터링, Flex-Ajax Bridge, 수동으로 생성하는 HTML wrapper 에서 사용되는 파일과 디렉토리, Flex SDK 소스 코드, 설정 파일. Flash Player 인스톨러는 Flex SDK ZIP 파일에 있습니다.

J2EE 웹 어플리케이션으로 BlazeDS 설치하기 / To install BlazeDS as a J2EE web application:

1. 알려진 이슈와 최신 정보가 담긴 BlazeDS 릴리즈 노트 를 읽으십시오.
2. ZIP 파일의 압축을 푸세요.
3. 어플리케이션 서버의 배포 방식에 따라 blazeds, 샘플, ds-console 웹 어플리케이션을 설치하십시오. 예를 들어, Tomcat 에서는 WAR 파일을 webapps 디렉토리에 복사하고 서버를 재시작 하십시오.
4. BlazeDS 샘플 어플리케이션은 install_root/sampledb 디렉토리에 설치된 HSQLDB 데이터베이스를 사용합니다. 샘플 데이터베이스를 시작하려면:
   • 명령창을 열고 install_root/sampledb 디렉토리로 이동하십시오.
   • startdb.bat (Windows) 이나 startdb.sh (Unix 기반의 시스템)를 실행하십시오.
5. 추가로 Additional server-specific configuration 에 설명된 어플리케이션 서버 설정을 수행하십시오.

샘플 실행 / Running the Test Drive with the integrated Tomcat install

In addition to the BlazeDS WAR file, the BlazeDS download includes a series of web applications fully configured with BlazeDS. To run the test drive after the install:

1. Start your application server.
2. The BlazeDS 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).
3. Open a browser window.
4. Access the samples home page by opening the following URL in a browser (the host name and port number of the deployed war file depends on the configuration of your web application):
   http://hostName:portNumber/samples/
5. Take the test drive!

추가적인 서버 설정 / Additional server-specific configuration

아래의 어플리케이션 서버를 위한 추가적인 설정이 필요할 수 있습니다:

• Tomcat 6
• WebSphere 6
• JBoss
• Running from a compressed WAR
• Integrating BlazeDS with a ColdFusion 8 installation

Tomcat

Tomcat 에서 BlazeDS 를 사용하려면, BlazeDS WAR 파일 배포 후 아래의 설정이 필요합니다. Tomcat 이 통합된 설치에서는 필요 없습니다.

1. JAVA_OPTS 변수에 JVM 의 최대 힙 크기를 명시함으로써 최대 메모리를 적어도 512MB 가 되도록 늘려주십시오: -Xmx512m
2. (Optional) 인증을 사용하기 위해 install_root/resources/security/tomcat 아래에 Tomcat 보안 리소스 라이브러리를 놓으십시오.
   1. tomcat/lib/blazeds 에 flex-tomcat-common.jar 추가.
   2. flex-tomcat-server.jar 를 tomcat/lib/blazeds 에 추가.
   3. tomcat/conf 디렉토리에 있는 catalina.properties 파일 수정. common.loader 속성의 마지막에 다음의 경로 추가: ${catalina.home}/lib/blazeds/*.jar
   4. <Valve className="flex.messaging.security.TomcatValve"/> 태그를 Context descriptor 에 추가. BlazeDS samples WAR 를 예로 들자면:
      <Context path="/samples" docBase="${catalina.home}/webapps/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 BlazeDS 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 BlazeDS WAR file. For Tomcat, ensure that the TomcatLoginCommand is active in the <security> section:
      <security>
      <login-command class="flex.messaging.security.TomcatLoginCommand" server="Tomcat" />
      ...
3. (Optional) Message Service 에 JSMAdapter 를 사용하기 위해, Tomcat 에서 사용할 수 있도록 activeMQ 나 openJMS 같은 JMS provider 를 설치하고 설정해야 합니다.
4. Tomcat 재시작.

Tomcat 6.0.x 에서 ActiveMQ 4.1.1 설정

These instructions create a configuration that matches what is distributed with BlazeDS. 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:

1. Download ActiveMQ 4.1.1 from http://activemq.apache.org.
2. Download and install the ActiveMQ distribution following the instructions provided on the ActiveMQ website.
3. 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
4. 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.
5. 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
6. Modify your BlazeDS 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>

7. 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.

8. 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 BlazeDS 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>

9. 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 onhttp://activemq.apache.org.

WebSphere

(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.

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 BlazeDS custom authentication, see the BlazeDS documentation and information in the install_root/resources/security directory.
Running from a compressed WAR

To run BlazeDS from a compressed WAR file, perform the following steps:

1. Expand the flex.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 BlazeDS 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 samples.war use HSQLDB which will not function within a compressed web application. It is therefore advised to deploy samples as an uncompressed war.
   Note that when running BlazeDS from a compressed WAR file some features, such as clustering are not available.

Integrating BlazeDS with a ColdFusion 8 installation

ColdFusion 8 comes either with an integrated LiveCycle Data Services ES installation or without one. The way you integrate BlazeDS with ColdFusion 8 depends on your version of ColdFusion.

If you have ColdFusion 8 installed with LiveCycle Data Services ES, you must perform both of the following procedures. If you have ColdFusion 8 without LiveCycle Data Services ES, you only have to perform the second procedure.

To integrate BlazeDS with ColdFusion 8 with integrated LiveCycle Data Services ES installation, perform these steps and perform the next procedure:

1. Shut down ColdFusion.
2. Move the contents of the ColdFusion8/wwwroot/WEB-INF/flex directory to a backup location so that the flex directory is now empty.
3. Edit ColdFusion8/WEB-INF/web.xml:
   • Comment out/remove the definitions of FlexMxmlServlet and FlexInternalServlet servlets.
   • Comment out/remove the servlet mapping for FlexMxmlServlet and FlexInternalServlet.
   • Comment out/remove the taglig definition for the FlexTagLib tag library.

Complete the following instructions for all versions of ColdFusion.

1. If you have not already done so, shut down ColdFusion.
2. Unzip blazeds.war in to a temporary directory (In this example c:\temp\BlazeDS).
3. Move aside the following jar files from ColdFusion8/lib:
   • flex-messaging.jar
   • flex-messaging-common.jar
   • flex-messaging-opt.jar
   • flex-messaging-req.jar
4. Copy the following jar files from c:\temp\BlazeDS\WEB-INF\lib to ColdFusion8/lib:
   • flex-messaging-common.jar
   • flex-messaging-core.jar
   • flex-messaging-opt.jar
   • flex-messaging-proxy.jar
   • flex-messaging-remoting.jar
5. Create a new directory (create the WEB-INF/flex directory if needed):
   ColdFusion8/wwwroot/WEB-INF/flex/jars
6. Copy the following jar files from c:\temp\BlazeDS\WEB-INF\lib to ColdFusion8/wwwroot/WEB-INF/flex/jars:
   • concurrent.jar
   • cfgatewayadapter
7. Set up the configuration files for BlazeDS. You can copy the set of configuration files from the BlazeDS ZIP file (not the WAR file). Copy the following files in resources/ColdFusion to ColdFusion8/wwwroot/WEB-INF/flex:
   • services-config.xml
   • messaging-config.xml
   • proxy-config.xml
   • remoting-config.xml
8. (Optional) You can continue to use the configuration files from your integrated LiveCycle Data Services ES installation by performing the following procedure:
   1. Copy services-config.xml, messaging-config.xml, proxy-config.xml, and remoting-config.xml from the WEB-INF/flex directory you moved aside earlier back to ColdFusion8/wwwroot/WEB-INF/flex.
   2. Remove from the following line from the services-config.xml file:
      <service-include file-path="data-management-config.xml" />
   3. Remove the <channel-definition> from the services-config.xml file for the ColdFusion-specific RTMP channel (if not commented out) and remove the java-http and java-secure-http channel definitions.
9. Uncomment the java-amf, java-secure-amf and java-polling-amf channels. Do not include the java-rtmp channel definition.
10. Edit the proxy-config.xml file and change the lines:
    <channel ref="java-http"/>
    <!-- <channel ref="java-amf"/> -->
    to the following text:
    <channel ref="java-amf"/>
11. Restart ColdFusion.

Upgrading BlazeDS 3 to version 3.2

BlazeDS 3.2 ships with an empty web application called blazeds.war. You likely used the blazeds.war from version 3 as the basis for the web application that you want to upgrade. You are going to use the blazeds.war from version 3.2 as the basis of your upgraded version 3 web application.

The following procedure describes how to upgrade an existing installation of BlazeDS 3 to BlazeDS 3.2:

1. Install BlazeDS 3.2.
2. Create a backup copy of your existing version 3 web application. As part of this procedure, you copy assets from the backup copy to the new BlazeDS 3.2 web application.
3. Uninstall your existing BlazeDS 3 web application from your application server. The steps to do this uninstall are based on your application server. For more information, see the documentation for your application server.
4. Expand the empty blazeds.war file installed with version 3.2. If you are starting with a packaged blazeds.war, you will need to expand it to a directory and then repackage it when you are finished.
5. Copy the assets from your existing version 3 web application to the empty BlazeDS 3.2 web application. Copy all image, font, SWF, Java, and JAR and other files required by your application.
   Note: Do not copy any configuration files from the WEB-INF/flex directory of your existing version 3 web application.
6. Merge the configuration files from the WEB-INF/flex directory of your existing version 3 web application to the configuration files in the WEB-INF/flex directory of the new BlazeDS 3.2 web application. To perform this merge, copy and paste your destination, channel, endpoint, and other definitions from the version 3 configuration files to the version 3.2 configuration files.
   Note: Because configuration files can contain new configuration properties, or change the default values of existing properties, do not overwrite the version 3.2 configuration files with the version 3 configuration files. Instead, always merge your custom settings into the version 3.2 configuration files.
7. (Optional) If you deploy a compressed or packaged web application, repackage the web application.
8. Deploy the new web application on your application server.