xdocs/install.xml - portals-pluto - Git at Google

 <?xml version="1.0"?>
 <!--
 Copyright 2004, 2005 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>
     <author email="unknown">Jean-Baptiste Joret</author>
     <author email="ddewolf.AT.apache.DOT.org">David H. DeWolf</author>
     <author email="nl.AT.essential.DOT.com.DOT.au">Nick Lothian</author>
     <author email="cdoremus.AT.apache.DOT.org">Craig Doremus</author>
     <title>Pluto Project</title>
   </properties>

 <body>

 <section name="Installation Guide">
 <p>This install guide covers the following types of installations:
 <ul><li><A href="#Installing_Distributions">Installing Distributions</A></li>
 <li><A href="#Installing_Portlets">Installing Portlets</A></li>
      <ul>
        <li><A href="#Installing_With_Maven">Using Maven to Install Portlets</A></li>
        <li><A href="#Using_the_Admin_Portlet_Application">Using the Admin Portlet App to Install Portlets</A></li>
      </ul>
 </ul>
 </p>
 </section>

 <section name="Installing Distributions">

 <subsection name="Binary Distribution">
 <p>The binary distribution of Pluto is packaged with Tomcat
    (currently version 5.5.9).  Pluto leverages Tomcat to
    provide the web container in which the Pluto portlet
    container executes. The binary distribution includes
    the Pluto Portlet Container, The Portal Driver, the
    Pluto Testsuite and the Admin Portlet application.</p>
 <p>To install the binary distribution:
    <ul>
    <li><A href="mirrors.cgi">Download</A>
        the current binary distribution of Pluto</li>
    <li>Extract the binary distribution to a directory
        from here forward refered to as "&lt;PLUTO_HOME&gt;".</li>
    <li>Startup the server by using the appropriate tomcat
        startup script located at &lt;PLUTO_HOME&gt;/bin.
        For *nix use startup.sh; for windows use startup.bat.</li>
    <li>By default Tomcat 5.5 uses JDK 1.5 (J2SE 5.0). In order to run it with
    JDK 1.4, a compatibility package needs to be downloaded and installed.
    See the Running.txt file in the root directory for details.
    </li>
    <li>Point your browser to
        <A href="http://localhost:8080/pluto/portal">The Pluto Driver</A>
        and your ready to go!</li>
    </ul>
 </p>
 </subsection>

 <subsection name="Library Distributions">
 <p>The pluto library distributions are packaged to allow
    integration with an external portal server.</p>
 <p>To install the library distributions to your portal server:
    <ul>Ensure that the pluto-x.x.x.jar is loaded by a classloader
        to which both the portal and portlet application web apps
        have access.</ul></p>

 </subsection>

 <subsection name="Source Distribution">
 <p>Installing the source distribution requires the most effort,
    and is recomended only for those individuals who are interested
    in modifying the container.  The source distribution is
    basically a snapshot of the source code repository at a given
    time. Because of this, please see the build instructions, which
    will provide information about how to build Pluto from scratch.
    </p>
 <p>To install the source distribution into tomcat:
    <ul>
    <li>Install Java 1.4 or greater</li>
    <li>Install Maven 1.0 or greater</li>
    <li>Install Tomcat 4.x or Tomcat 5.x to
        a directory from here forward refered to as
        &lt;TOMCAT_HOME&gt;</li>
    <li>Edit your &lt;PLUTO_HOME&gt;/build.properties to include
        the following properties:
        <table><tr><th>Property</th><th>Value</th><th>Example(s)</th></tr>
               <tr><td>maven.tomcat.home</td>
                   <td>Tomcat Installation Directory</td>
                   <td><code>\\usr\\local\\jakarta-tomcat.5.0.27</code>,
                       <code>c:\\jakarta-tomcat.5.0.27</code></td></tr>
               <tr><td>maven.tomcat.version.major</td>
                   <td>Tomcat Major Version Number</td>
                   <td>5</td></tr>
        </table></li>
     <li>From &lt;PLUTO_HOME&gt; issue the command:
         <code>'maven fullDeployment'</code></li>
     <li>Startup the server by using the appropriate tomcat
        startup script located at &lt;PLUTO_HOME&gt;/bin.
        For *nix use startup.sh; for windows use startup.bat.</li>
     <li>Point your browser to
        <A href="http://localhost:8080/pluto/portal">The Pluto Driver</A>
        and your ready to go!</li>
    </ul>
 </p>
 </subsection>
 </section>

 <section name="Installing Portlets">
 <subsection name="Installing With Maven">
 <p><FONT color="red">
   Currently, to automate the deployment/installation of portlets
   you must utilize the source distribution of pluto.
 Alternatively, you could use the <a href="#Using_the_Admin_Portlet_Application">Admin Portlet Application</a>
 to install custom portlets.
   </FONT></p>

 <p>In order to deploy a portlet application to pluto, you must
    follow the steps below:
 </p>
   <ul>
   <li>Assemble your portlet application into a valid war.</li>
   <li><p>Run the maven deploy goal on your war</p>
       <p>This can be done by running this command line in the deploy subdirectory:<br/>
          <pre>maven deploy -Ddeploy=/MyPathToMyPortlet/target/MyPortlet.war</pre>
       </p>
       <p>See the <a href="developer/build_source.html">Building From Source</a> document for detailed instructions.</p></li>

 	<p>Alternatively, there is an interactive ant script in the <tt>portlet-deploy</tt> directory
 	that will perform the same task as the Maven deployment goal.</p>

   <li>Modify the Portlet Entity Registry and the Page Registry and Portlet Contexts files.  These
       configuration files are located at:
 <pre>
       [portal-home]/WEB-INF/data/portletentityregistry.xml

       [portal-home]/WEB-INF/data/pageregistry.xml

       [portal-home]/WEB-INF/data/portletcontexts.txt
 </pre>

 <p>
 The Portlet Entity Registry file requires that you specify an application and
 a Portlet ID for your new Portlet. The Application ID must be unique. It also
 needs to know the name of the Portlet so that it can go out and find it in
 the webapps path. Furthermore, this information is used to map the Portlet
 name to the appropriate class path for loading the class. The following is an
 example of some additions you can make to the entity registry file:
 </p>

 <pre>
 &lt;application id="6"&gt;
   &lt;definition-id&gt;MyPortlet&lt;/definition-id&gt;
   &lt;portlet id="1"&gt;
       &lt;definition-id&gt;MyPortlet.MyPortlet&lt;/definition-id&gt;
   &lt;/portlet&gt;
 &lt;/application&gt;
 </pre>

 <p>
 The Page Registry provides Pluto with the layout information for your Portlet.
 The names used in the fragments must be unique as done in the following example:
 </p>

 <pre>
 &lt;fragment name="MyPortlet" type="page"&gt;
   &lt;navigation&gt;
     &lt;title&gt;My First Portlet&lt;/title&gt;
     &lt;description&gt;...&lt;/description&gt;
   &lt;/navigation&gt;

   &lt;fragment name="row3" type="row"&gt;
     &lt;fragment name="col3" type="column"&gt;
       &lt;fragment name="p4" type="portlet"&gt;
         &lt;property name="portlet" value="6.1"/&gt;
       &lt;/fragment&gt;
     &lt;/fragment&gt;
   &lt;/fragment&gt;
 </pre>


 <p>
 The Portlet Contexts file (portletcontexts.txt) lists the webapp contexts for each portlet application
 that runs in Pluto. Each portlet app has a line in this file corresponding to a path and starting with
 a slash ('/'). In Tomcat, this path is the value of the 'path' attribute of the 'Context' element in
 a context XML descriptor in $TOMCAT_HOME/conf/Catalina/localhost (or another 'conf' subdirectory).
 </p>


 </li>
 </ul>
 </subsection>

 <subsection name="Using the Admin Portlet Application">
 <p>The Admin Portlet Application allows you to deploy custom portlets using an
 interface in Pluto's portal. This application automatically places the custom
 portlets to their proper place and updates the registries.
 </p>
 <p>Deploying a custom portlet application to Pluto using the Admin Portlet App
    requires the following steps:
 </p>
   <ul>
   <li>Assemble your portlet application into a valid war.</li>
   <li>Start Pluto and navigate to the <a href="http://localhost:8080/pluto/portal">local Pluto home page</a></li>
   <li>Click on the Admin navigation link. The Admin Portlet App should appear.</li>
   <li>In the Deploy War Portlet, click on the Browse button and select your war file</li>
   <li>Click on the Submit button of the Deploy War Portlet</li>
   <li>In the resulting page, fill in the Title, Description (optional), and the number
   of rows and columns you desire for laying out the portlets. Click on Submit</li>
   <li>In the resulting page, select from the drop downs which portlet will be deployed
   in a particular row and column. Click on Submit.</li>
   <li>After returning to the Deploy War Portlet 'home page', click on the blue 'Hot deploy . . .'
   link to hot deploy the new portlet app and get redirected to its page.</li>
   </ul>
   <p>Check out the Deploy War Portlet's help mode (help link) for information
   on redeploying and undeploying portlets and troubleshooting problems.</p>
 </subsection>
 </section>

 </body>
 </document>
	<?xml version="1.0"?>
	<!--
	Copyright 2004, 2005 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>
	<author email="unknown">Jean-Baptiste Joret</author>
	<author email="ddewolf.AT.apache.DOT.org">David H. DeWolf</author>
	<author email="nl.AT.essential.DOT.com.DOT.au">Nick Lothian</author>
	<author email="cdoremus.AT.apache.DOT.org">Craig Doremus</author>
	<title>Pluto Project</title>
	</properties>

	<body>

	<section name="Installation Guide">
	<p>This install guide covers the following types of installations:
	<ul><li><A href="#Installing_Distributions">Installing Distributions</A></li>
	<li><A href="#Installing_Portlets">Installing Portlets</A></li>
	<ul>
	<li><A href="#Installing_With_Maven">Using Maven to Install Portlets</A></li>
	<li><A href="#Using_the_Admin_Portlet_Application">Using the Admin Portlet App to Install Portlets</A></li>
	</ul>
	</ul>
	</p>
	</section>

	<section name="Installing Distributions">

	<subsection name="Binary Distribution">
	<p>The binary distribution of Pluto is packaged with Tomcat
	(currently version 5.5.9). Pluto leverages Tomcat to
	provide the web container in which the Pluto portlet
	container executes. The binary distribution includes
	the Pluto Portlet Container, The Portal Driver, the
	Pluto Testsuite and the Admin Portlet application.</p>
	<p>To install the binary distribution:
	<ul>
	<li><A href="mirrors.cgi">Download</A>
	the current binary distribution of Pluto</li>
	<li>Extract the binary distribution to a directory
	from here forward refered to as "<PLUTO_HOME>".</li>
	<li>Startup the server by using the appropriate tomcat
	startup script located at <PLUTO_HOME>/bin.
	For *nix use startup.sh; for windows use startup.bat.</li>
	<li>By default Tomcat 5.5 uses JDK 1.5 (J2SE 5.0). In order to run it with
	JDK 1.4, a compatibility package needs to be downloaded and installed.
	See the Running.txt file in the root directory for details.
	</li>
	<li>Point your browser to
	<A href="http://localhost:8080/pluto/portal">The Pluto Driver</A>
	and your ready to go!</li>
	</ul>
	</p>
	</subsection>

	<subsection name="Library Distributions">
	<p>The pluto library distributions are packaged to allow
	integration with an external portal server.</p>
	<p>To install the library distributions to your portal server:
	<ul>Ensure that the pluto-x.x.x.jar is loaded by a classloader
	to which both the portal and portlet application web apps
	have access.</ul></p>

	</subsection>

	<subsection name="Source Distribution">
	<p>Installing the source distribution requires the most effort,
	and is recomended only for those individuals who are interested
	in modifying the container. The source distribution is
	basically a snapshot of the source code repository at a given
	time. Because of this, please see the build instructions, which
	will provide information about how to build Pluto from scratch.
	</p>
	<p>To install the source distribution into tomcat:
	<ul>
	<li>Install Java 1.4 or greater</li>
	<li>Install Maven 1.0 or greater</li>
	<li>Install Tomcat 4.x or Tomcat 5.x to
	a directory from here forward refered to as
	<TOMCAT_HOME></li>
	<li>Edit your <PLUTO_HOME>/build.properties to include
	the following properties:
	<table><tr><th>Property</th><th>Value</th><th>Example(s)</th></tr>
	<tr><td>maven.tomcat.home</td>
	<td>Tomcat Installation Directory</td>
	<td><code>\\usr\\local\\jakarta-tomcat.5.0.27</code>,
	<code>c:\\jakarta-tomcat.5.0.27</code></td></tr>
	<tr><td>maven.tomcat.version.major</td>
	<td>Tomcat Major Version Number</td>
	<td>5</td></tr>
	</table></li>
	<li>From <PLUTO_HOME> issue the command:
	<code>'maven fullDeployment'</code></li>
	<li>Startup the server by using the appropriate tomcat
	startup script located at <PLUTO_HOME>/bin.
	For *nix use startup.sh; for windows use startup.bat.</li>
	<li>Point your browser to
	<A href="http://localhost:8080/pluto/portal">The Pluto Driver</A>
	and your ready to go!</li>
	</ul>
	</p>
	</subsection>
	</section>

	<section name="Installing Portlets">
	<subsection name="Installing With Maven">
	<p><FONT color="red">
	Currently, to automate the deployment/installation of portlets
	you must utilize the source distribution of pluto.
	Alternatively, you could use the <a href="#Using_the_Admin_Portlet_Application">Admin Portlet Application</a>
	to install custom portlets.
	</FONT></p>

	<p>In order to deploy a portlet application to pluto, you must
	follow the steps below:
	</p>
	<ul>
	<li>Assemble your portlet application into a valid war.</li>
	<li><p>Run the maven deploy goal on your war</p>
	<p>This can be done by running this command line in the deploy subdirectory:<br/>
	<pre>maven deploy -Ddeploy=/MyPathToMyPortlet/target/MyPortlet.war</pre>
	</p>
	<p>See the <a href="developer/build_source.html">Building From Source</a> document for detailed instructions.</p></li>

	<p>Alternatively, there is an interactive ant script in the <tt>portlet-deploy</tt> directory
	that will perform the same task as the Maven deployment goal.</p>

	<li>Modify the Portlet Entity Registry and the Page Registry and Portlet Contexts files. These
	configuration files are located at:
	<pre>
	[portal-home]/WEB-INF/data/portletentityregistry.xml

	[portal-home]/WEB-INF/data/pageregistry.xml

	[portal-home]/WEB-INF/data/portletcontexts.txt
	</pre>

	<p>
	The Portlet Entity Registry file requires that you specify an application and
	a Portlet ID for your new Portlet. The Application ID must be unique. It also
	needs to know the name of the Portlet so that it can go out and find it in
	the webapps path. Furthermore, this information is used to map the Portlet
	name to the appropriate class path for loading the class. The following is an
	example of some additions you can make to the entity registry file:
	</p>

	<pre>
	<application id="6">
	<definition-id>MyPortlet</definition-id>
	<portlet id="1">
	<definition-id>MyPortlet.MyPortlet</definition-id>
	</portlet>
	</application>
	</pre>

	<p>
	The Page Registry provides Pluto with the layout information for your Portlet.
	The names used in the fragments must be unique as done in the following example:
	</p>

	<pre>
	<fragment name="MyPortlet" type="page">
	<navigation>
	<title>My First Portlet</title>
	<description>...</description>
	</navigation>

	<fragment name="row3" type="row">
	<fragment name="col3" type="column">
	<fragment name="p4" type="portlet">
	<property name="portlet" value="6.1"/>
	</fragment>
	</fragment>
	</fragment>
	</pre>


	<p>
	The Portlet Contexts file (portletcontexts.txt) lists the webapp contexts for each portlet application
	that runs in Pluto. Each portlet app has a line in this file corresponding to a path and starting with
	a slash ('/'). In Tomcat, this path is the value of the 'path' attribute of the 'Context' element in
	a context XML descriptor in $TOMCAT_HOME/conf/Catalina/localhost (or another 'conf' subdirectory).
	</p>


	</li>
	</ul>
	</subsection>

	<subsection name="Using the Admin Portlet Application">
	<p>The Admin Portlet Application allows you to deploy custom portlets using an
	interface in Pluto's portal. This application automatically places the custom
	portlets to their proper place and updates the registries.
	</p>
	<p>Deploying a custom portlet application to Pluto using the Admin Portlet App
	requires the following steps:
	</p>
	<ul>
	<li>Assemble your portlet application into a valid war.</li>
	<li>Start Pluto and navigate to the <a href="http://localhost:8080/pluto/portal">local Pluto home page</a></li>
	<li>Click on the Admin navigation link. The Admin Portlet App should appear.</li>
	<li>In the Deploy War Portlet, click on the Browse button and select your war file</li>
	<li>Click on the Submit button of the Deploy War Portlet</li>
	<li>In the resulting page, fill in the Title, Description (optional), and the number
	of rows and columns you desire for laying out the portlets. Click on Submit</li>
	<li>In the resulting page, select from the drop downs which portlet will be deployed
	in a particular row and column. Click on Submit.</li>
	<li>After returning to the Deploy War Portlet 'home page', click on the blue 'Hot deploy . . .'
	link to hot deploy the new portlet app and get redirected to its page.</li>
	</ul>
	<p>Check out the Deploy War Portlet's help mode (help link) for information
	on redeploying and undeploying portlets and troubleshooting problems.</p>
	</subsection>
	</section>

	</body>
	</document>