trunk/pluto-site/src/site/xdoc/v11/deploying.xml - portals-pluto - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 Copyright 2004-2006 The Apache Software Foundation
 Licensed  under the  Apache License,  Version 2.0  (the "License");
 you may not use  this file  except in  compliance with the License.
 You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed  under the  License is distributed on an "AS IS" BASIS,
 WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
 implied.

 See the License for the specific language governing permissions and
 limitations under the License.
 -->

 <document>

   <properties>
     <title>Deploying Portlet to Pluto Portal</title>
     <author email="zheng.at.apache.D0T.org">ZHENG Zhong</author>
     <author email="ddewolf@apache.org">David DeWolf</author>
     <author email="cdoremus@apache.org">Craig Doremus</author>
   </properties>

   <body>

     <section name="Deploying Portlet to Pluto Portal">

       <p>
         There are 3 steps to deploy a portlet to Pluto 1.1:
         <ul>
           <li>
             <b>Assembly</b>: All portlet applications must be run through the
             pluto assembler before being deployed. The assembly process injects
             pluto specific information for deployment. Specifically, a servlet
             and servlet mapping are added to the deployment descriptor (web.xml).
             This servlet (<code>org.apache.pluto.core.PortletServlet</code>) will be
             used to dispatch portlet requests to the portlet application.
           </li>
           <li>
             <b>Deployment</b>: After portlet applications are assembled properly
             they must be deployed to the servlet engine within which the portal
             application is running. The current binary distribution uses
             Tomcat 5.5 as the servlet engine.
           </li>
           <li>
             <b>Publishing</b>: All portlet applications that are to be used
             within the Pluto Portal must be published to the Portal. Publishing
             notifies the Portal Application that a portlet application is bound
             (deployed) to a certain context within the appserver. This is done
             by adding records to <code>pluto-portal-driver-config.xml</code>.
           </li>
         </ul>
       </p>

       <subsection name="Portlet Assembly and Deployment using Maven 2">
         <p>
         As of the second beta release of Pluto 1.1, the Maven 2 plugins for assembly and
         deployment are partially completed.
           Right now the maven-pluto-plugin correctly assembles the war with
           the proper <code>PortletServlet</code> records to web.xml, but the
           deployment plugin is not yet completed. We have created an example
           <!-- TODO: Review use of the word deploys -->
           Maven 2 pom.xml below that correctly assembles and deploys the portlet.
         </p>
         <p>
           The custom Maven 2 build shown below also deploys
           a Tomcat context deployment descriptor that has the same name as your
           artifactId with an xml extension (e.g. HelloWorldPortlet.xml).
         </p>
         <p>
           To properly assemble and deploy your portlet using the Maven 2 script (pom.xml) below,
           your project's directory structure and artifact placement must conform to Maven's standard:
         </p>
         <p>
           <source><![CDATA[
 	HelloWorldPortlet (top level directory)
 	|- pom.xml (the pom file)
 	|- src (Subdir containing main subdirectory)
 	    |- main (Subdir containing java, resources and webapp subdirs)
 	    	|- java (java source code goes under here)
 		    |       `- com
 		    |           `- mycompany
 		    |               `- portlet
 		    |                   `- HelloWorldPortlet.java (portlet source)
 		    |- resources
 		    |	`- HelloWorldPortlet.xml (Tomcat context deployment descriptor)
 		    |- webapp  (webapp resources (jsp, css, images) go under here)
 		    	`- jsp
 		    		`- HelloWorldPortletView.jsp (for view mode)
 		    		`- HelloWorldPortletEdit.jsp (for edit mode)
 		    	`- WEB-INF
 			    	`- portlet.xml (JSR-168 deployment descriptor)
 			    	`- web.xml (This will be modified by maven-pluto-plugin)
           ]]></source>
         </p>

         <p>
         This is an example of what the Tomcat context deployment descriptor will contain:
           <source><![CDATA[
 		<Context path="HelloWorldPortlet"
 			docBase="../PlutoDomain/HelloWorldPortlet.war"
 			crossContext="true"/>
           ]]></source>
         </p>
         <p>
         The Maven 2 pom file (pom.xml) is what defines the build. Our example overrides
         the integration-test lifecycle phase in addition to using the maven-pluto-plugin
         to assemble the war. Use this as you pom file, changing the groupId, artifactId and version
         to values appropriate to your custom portlet.
           <source><![CDATA[
 <project xmlns="http://maven.apache.org/POM/4.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

   <!-- Change this to something akin to your java package structure -->
   <groupId>com.mycompany.portlet</groupId>
   <modelVersion>4.0.0</modelVersion>
   <!-- Version of this app -->
   <version>0.1-alpha1</version>
   <!-- Base name of the war file without .war ext -->
   <artifactId>HelloWorldPortlet</artifactId>
   <packaging>war</packaging>
   <name>${pom.artifactId}</name>
   <!-- Dependency Version Properties ======================================= -->
   <properties>
   	<!-- Change this for a new Pluto version -->
     <pluto.version>1.1.0-beta2</pluto.version>
     <portlet-api.version>1.0</portlet-api.version>
     <servlet-api.version>2.3</servlet-api.version>
     <jsp-api.version>2.0</jsp-api.version>
     <junit.version>3.8.1</junit.version>
   </properties>
   <dependencies>
     <dependency>
       <groupId>javax.portlet</groupId>
       <artifactId>portlet-api</artifactId>
       <version>${portlet-api.version}</version>
       <scope>provided</scope><!-- Prevents addition to war file -->
     </dependency>
     <dependency>
       <groupId>javax.servlet</groupId>
       <artifactId>servlet-api</artifactId>
       <version>${servlet-api.version}</version>
       <scope>provided</scope>
     </dependency>
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
       <version>${junit.version}</version>
       <scope>test</scope>
     </dependency>
     <dependency>
       <groupId>org.apache.pluto</groupId>
       <artifactId>pluto-util</artifactId>
       <version>${pluto.version}</version>
       <scope>provided</scope>
     </dependency>
     <!-- Any other build or deployment dependancies go here -->
   </dependencies>
   <build>
     <finalName>${pom.name}</finalName>
     <plugins>
       <!-- configure maven-war-plugin to use updated web.xml -->
       <plugin>
         <artifactId>maven-war-plugin</artifactId>
         <configuration>
           <webXml>${project.build.directory}/pluto-resources/web.xml</webXml>
         </configuration>
       </plugin>
       <!-- bind 'pluto:assemble' goal to 'process-resources' lifecycle -->
       <plugin>
         <groupId>org.apache.pluto</groupId>
         <artifactId>maven-pluto-plugin</artifactId>
         <version>${pluto.version}</version>
         <executions>
           <execution>
             <phase>generate-resources</phase>
             <goals>
               <goal>assemble</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
       <plugin>
       	<!-- Override the 'integration-test' lifecycle phase
       	with a custom one that runs a simple Ant script -->
         <artifactId>maven-antrun-plugin</artifactId>
         <executions>
           <execution>
             <phase>integration-test</phase>
             <configuration>
               <tasks>
               	<!-- Set tomcat.home to CATALINA_HOME environmental variable
               	Use this to skip -Dpluto.home=/path/to/pluto on command line -->
               	<property environment="env"/>
               	<property name="pluto.home" value="${env.CATALINA_HOME}"/>
               	<echo message="pluto.home=${pluto.home}"/>
               	<!-- Remove former deployment because sometimes
               	tomcat does not fully redeploy a war -->
                 <delete
                   dir="${pluto.home}/webapps/${pom.name}"
                   failonerror="true"
                 />
               	<!-- Deploy war file -->
                 <copy
                   file="${project.build.directory}/${pom.name}.war"
                   todir="${pluto.home}/PlutoDomain"
                   overwrite="true"
                 />
               	<!-- Deploy context deployment descriptor for Tomcat -->
                 <copy
                   file="${basedir}/src/main/resources/${pom.name}.xml"
                   todir="${pluto.home}/conf/Catalina/localhost"
                   overwrite="false"
                 />
               </tasks>
             </configuration>
             <goals>
               <goal>run</goal>
             </goals>
           </execution>
         </executions>
       </plugin>
     </plugins>
   </build>

 </project>
           ]]></source>
         </p>
         <p>
 			Run the Maven 2 pom.xml script using 'mvn integration-test -Dpluto.home=/path/to/pluto1.1install'
 			from the command line to create the war with web.xml modified for deployment to
 			Pluto-1.1 and deploy it to a local install of Pluto-1.1.
 			The embedded Ant script in the pom.xml was created to use the environmental variable
 			CATALINA_HOME as the value of pluto.home.
 			If you have set CATALINA_HOME to your Pluto-1.1 install, then you can just run
 			the command 'mvn integration-test'.
         </p>
         <p>
 			If you prefer to manually deploy the war to Tomcat, run 'mvn package' which will
 			create the war file in the <code>target/</code> directory.  Then manually deploy
 			the war file and Tomcat context deployment descriptor to your Pluto-1.1 install.
         </p>
       </subsection>

       <subsection name="Portlet Publishing">
         <p>
           Currently, as of Pluto-1.1-beta2, the only way to publish an application to the portal
           is to manually update the Portal's configuration file <code>pluto-portal-driver-config.xml</code>
           located in the WEB-INF directory of the pluto webapp.
           Here's how to do it:
         </p>

         <p><b>Step 1: Portlet App Config</b></p>
         <p>
           First, add a <code>portlet-app</code> config element to
           notify the Portal which portlet application is deployed to the
           appserver (Tomcat). In this element, you should specify the context path of
           your portlet app, as well as the names of portlets deployed. Here is
           an example:
           <source><![CDATA[
 <portlet-app>
   <context-path>/your_portlet_app_context_path</context-path>
   <portlets>
     <portlet name="your_portlet_1"/>
     <portlet name="your_portlet_2"/>
     ... ...
   </portlets>
 </portlet-app>
           ]]></source>
         </p>

         <p><b>Step 2: Portal Page Config</b></p>
         <p>
           You should then configure a portal page to display your portlets.
           Do this by adding a <code>page</code> element in the <code>render-config</code>
           element, like this:
           <source><![CDATA[
 <render-config default="Test Page">
   ... ...
   <page name="Your Portal Page Name" uri="/WEB-INF/fragments/portlet.jsp">
     <portlet context="/your_portlet_app_context_path"
              name="your_portlet_1"/>
     <portlet context="/your_portlet_app_context_path"
              name="your_portlet_2"/>
   </page>
 </render-config>
           ]]></source>
         </p>
         <p>
           The <code>uri</code> attribute defines the theme of your portal page.
           If you use <code>/WEB-INF/fragments/portlet.jsp</code> (which is the
           default theme of Pluto Testsuite portlet app), your portlets will be
           displayed in two columns. You can clone this file to customize your layout.
           If you do so, make sure the <code>uri</code> attribute points to the new file.
         </p>
       </subsection>

     </section>

   </body>

 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Copyright 2004-2006 The Apache Software Foundation
	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
	implied.

	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<document>

	<properties>
	<title>Deploying Portlet to Pluto Portal</title>
	<author email="zheng.at.apache.D0T.org">ZHENG Zhong</author>
	<author email="ddewolf@apache.org">David DeWolf</author>
	<author email="cdoremus@apache.org">Craig Doremus</author>
	</properties>

	<body>

	<section name="Deploying Portlet to Pluto Portal">

	<p>
	There are 3 steps to deploy a portlet to Pluto 1.1:
	<ul>
	<li>
	<b>Assembly</b>: All portlet applications must be run through the
	pluto assembler before being deployed. The assembly process injects
	pluto specific information for deployment. Specifically, a servlet
	and servlet mapping are added to the deployment descriptor (web.xml).
	This servlet (<code>org.apache.pluto.core.PortletServlet</code>) will be
	used to dispatch portlet requests to the portlet application.
	</li>
	<li>
	<b>Deployment</b>: After portlet applications are assembled properly
	they must be deployed to the servlet engine within which the portal
	application is running. The current binary distribution uses
	Tomcat 5.5 as the servlet engine.
	</li>
	<li>
	<b>Publishing</b>: All portlet applications that are to be used
	within the Pluto Portal must be published to the Portal. Publishing
	notifies the Portal Application that a portlet application is bound
	(deployed) to a certain context within the appserver. This is done
	by adding records to <code>pluto-portal-driver-config.xml</code>.
	</li>
	</ul>
	</p>

	<subsection name="Portlet Assembly and Deployment using Maven 2">
	<p>
	As of the second beta release of Pluto 1.1, the Maven 2 plugins for assembly and
	deployment are partially completed.
	Right now the maven-pluto-plugin correctly assembles the war with
	the proper <code>PortletServlet</code> records to web.xml, but the
	deployment plugin is not yet completed. We have created an example
	<!-- TODO: Review use of the word deploys -->
	Maven 2 pom.xml below that correctly assembles and deploys the portlet.
	</p>
	<p>
	The custom Maven 2 build shown below also deploys
	a Tomcat context deployment descriptor that has the same name as your
	artifactId with an xml extension (e.g. HelloWorldPortlet.xml).
	</p>
	<p>
	To properly assemble and deploy your portlet using the Maven 2 script (pom.xml) below,
	your project's directory structure and artifact placement must conform to Maven's standard:
	</p>
	<p>
	<source><![CDATA[
	HelloWorldPortlet (top level directory)
	\|- pom.xml (the pom file)
	\|- src (Subdir containing main subdirectory)
	\|- main (Subdir containing java, resources and webapp subdirs)
	\|- java (java source code goes under here)
	\| `- com
	\| `- mycompany
	\| `- portlet
	\| `- HelloWorldPortlet.java (portlet source)
	\|- resources
	\| `- HelloWorldPortlet.xml (Tomcat context deployment descriptor)
	\|- webapp (webapp resources (jsp, css, images) go under here)
	`- jsp
	`- HelloWorldPortletView.jsp (for view mode)
	`- HelloWorldPortletEdit.jsp (for edit mode)
	`- WEB-INF
	`- portlet.xml (JSR-168 deployment descriptor)
	`- web.xml (This will be modified by maven-pluto-plugin)
	]]></source>
	</p>

	<p>
	This is an example of what the Tomcat context deployment descriptor will contain:
	<source><![CDATA[
	<Context path="HelloWorldPortlet"
	docBase="../PlutoDomain/HelloWorldPortlet.war"
	crossContext="true"/>
	]]></source>
	</p>
	<p>
	The Maven 2 pom file (pom.xml) is what defines the build. Our example overrides
	the integration-test lifecycle phase in addition to using the maven-pluto-plugin
	to assemble the war. Use this as you pom file, changing the groupId, artifactId and version
	to values appropriate to your custom portlet.
	<source><![CDATA[
	<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

	<!-- Change this to something akin to your java package structure -->
	<groupId>com.mycompany.portlet</groupId>
	<modelVersion>4.0.0</modelVersion>
	<!-- Version of this app -->
	<version>0.1-alpha1</version>
	<!-- Base name of the war file without .war ext -->
	<artifactId>HelloWorldPortlet</artifactId>
	<packaging>war</packaging>
	<name>${pom.artifactId}</name>
	<!-- Dependency Version Properties ======================================= -->
	<properties>
	<!-- Change this for a new Pluto version -->
	<pluto.version>1.1.0-beta2</pluto.version>
	<portlet-api.version>1.0</portlet-api.version>
	<servlet-api.version>2.3</servlet-api.version>
	<jsp-api.version>2.0</jsp-api.version>
	<junit.version>3.8.1</junit.version>
	</properties>
	<dependencies>
	<dependency>
	<groupId>javax.portlet</groupId>
	<artifactId>portlet-api</artifactId>
	<version>${portlet-api.version}</version>
	<scope>provided</scope><!-- Prevents addition to war file -->
	</dependency>
	<dependency>
	<groupId>javax.servlet</groupId>
	<artifactId>servlet-api</artifactId>
	<version>${servlet-api.version}</version>
	<scope>provided</scope>
	</dependency>
	<dependency>
	<groupId>junit</groupId>
	<artifactId>junit</artifactId>
	<version>${junit.version}</version>
	<scope>test</scope>
	</dependency>
	<dependency>
	<groupId>org.apache.pluto</groupId>
	<artifactId>pluto-util</artifactId>
	<version>${pluto.version}</version>
	<scope>provided</scope>
	</dependency>
	<!-- Any other build or deployment dependancies go here -->
	</dependencies>
	<build>
	<finalName>${pom.name}</finalName>
	<plugins>
	<!-- configure maven-war-plugin to use updated web.xml -->
	<plugin>
	<artifactId>maven-war-plugin</artifactId>
	<configuration>
	<webXml>${project.build.directory}/pluto-resources/web.xml</webXml>
	</configuration>
	</plugin>
	<!-- bind 'pluto:assemble' goal to 'process-resources' lifecycle -->
	<plugin>
	<groupId>org.apache.pluto</groupId>
	<artifactId>maven-pluto-plugin</artifactId>
	<version>${pluto.version}</version>
	<executions>
	<execution>
	<phase>generate-resources</phase>
	<goals>
	<goal>assemble</goal>
	</goals>
	</execution>
	</executions>
	</plugin>
	<plugin>
	<!-- Override the 'integration-test' lifecycle phase
	with a custom one that runs a simple Ant script -->
	<artifactId>maven-antrun-plugin</artifactId>
	<executions>
	<execution>
	<phase>integration-test</phase>
	<configuration>
	<tasks>
	<!-- Set tomcat.home to CATALINA_HOME environmental variable
	Use this to skip -Dpluto.home=/path/to/pluto on command line -->
	<property environment="env"/>
	<property name="pluto.home" value="${env.CATALINA_HOME}"/>
	<echo message="pluto.home=${pluto.home}"/>
	<!-- Remove former deployment because sometimes
	tomcat does not fully redeploy a war -->
	<delete
	dir="${pluto.home}/webapps/${pom.name}"
	failonerror="true"
	/>
	<!-- Deploy war file -->
	<copy
	file="${project.build.directory}/${pom.name}.war"
	todir="${pluto.home}/PlutoDomain"
	overwrite="true"
	/>
	<!-- Deploy context deployment descriptor for Tomcat -->
	<copy
	file="${basedir}/src/main/resources/${pom.name}.xml"
	todir="${pluto.home}/conf/Catalina/localhost"
	overwrite="false"
	/>
	</tasks>
	</configuration>
	<goals>
	<goal>run</goal>
	</goals>
	</execution>
	</executions>
	</plugin>
	</plugins>
	</build>

	</project>
	]]></source>
	</p>
	<p>
	Run the Maven 2 pom.xml script using 'mvn integration-test -Dpluto.home=/path/to/pluto1.1install'
	from the command line to create the war with web.xml modified for deployment to
	Pluto-1.1 and deploy it to a local install of Pluto-1.1.
	The embedded Ant script in the pom.xml was created to use the environmental variable
	CATALINA_HOME as the value of pluto.home.
	If you have set CATALINA_HOME to your Pluto-1.1 install, then you can just run
	the command 'mvn integration-test'.
	</p>
	<p>
	If you prefer to manually deploy the war to Tomcat, run 'mvn package' which will
	create the war file in the <code>target/</code> directory. Then manually deploy
	the war file and Tomcat context deployment descriptor to your Pluto-1.1 install.
	</p>
	</subsection>

	<subsection name="Portlet Publishing">
	<p>
	Currently, as of Pluto-1.1-beta2, the only way to publish an application to the portal
	is to manually update the Portal's configuration file <code>pluto-portal-driver-config.xml</code>
	located in the WEB-INF directory of the pluto webapp.
	Here's how to do it:
	</p>

	<p><b>Step 1: Portlet App Config</b></p>
	<p>
	First, add a <code>portlet-app</code> config element to
	notify the Portal which portlet application is deployed to the
	appserver (Tomcat). In this element, you should specify the context path of
	your portlet app, as well as the names of portlets deployed. Here is
	an example:
	<source><![CDATA[
	<portlet-app>
	<context-path>/your_portlet_app_context_path</context-path>
	<portlets>
	<portlet name="your_portlet_1"/>
	<portlet name="your_portlet_2"/>
	... ...
	</portlets>
	</portlet-app>
	]]></source>
	</p>

	<p><b>Step 2: Portal Page Config</b></p>
	<p>
	You should then configure a portal page to display your portlets.
	Do this by adding a <code>page</code> element in the <code>render-config</code>
	element, like this:
	<source><![CDATA[
	<render-config default="Test Page">
	... ...
	<page name="Your Portal Page Name" uri="/WEB-INF/fragments/portlet.jsp">
	<portlet context="/your_portlet_app_context_path"
	name="your_portlet_1"/>
	<portlet context="/your_portlet_app_context_path"
	name="your_portlet_2"/>
	</page>
	</render-config>
	]]></source>
	</p>
	<p>
	The <code>uri</code> attribute defines the theme of your portal page.
	If you use <code>/WEB-INF/fragments/portlet.jsp</code> (which is the
	default theme of Pluto Testsuite portlet app), your portlets will be
	displayed in two columns. You can clone this file to customize your layout.
	If you do so, make sure the <code>uri</code> attribute points to the new file.
	</p>
	</subsection>

	</section>

	</body>

	</document>