| <?xml version="1.0" encoding="UTF-8"?> | |
| <!-- | |
| 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> | |
| <author email="zheng.AT.apache.DOT.org">ZHENG Zhong</author> | |
| <title>Getting Started with Pluto 1.0.1</title> | |
| </properties> | |
| <body> | |
| <section name="Installation Guide"> | |
| <p> | |
| This install guide covers the following types of installations: | |
| <ul> | |
| <li><a href="#Installing_Pluto_Distributions">Installing Pluto Distributions</a></li> | |
| <li><a href="#Installing_Portlets">Installing Portlets</a></li> | |
| <ul> | |
| <li><a href="#Installing_With_Maven">Installing with Maven</a></li> | |
| <li><a href="#Using_the_Admin_Portlet_Application">Using the Admin Portlet Application</a></li> | |
| </ul> | |
| </ul> | |
| </p> | |
| </section> | |
| <section name="Installing Pluto 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 <code>"<PLUTO_HOME>"</code>.</li> | |
| <li>Startup the server by using the appropriate tomcat startup | |
| script located at <code><PLUTO_HOME>/bin</code>. | |
| For *nix use <code>startup.sh</code>; for windows use | |
| <code>startup.bat</code>.</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 <code>http://localhost:8080/pluto/portal</code>, | |
| the Pluto Driver, 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, 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. | |
| </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 <code><TOMCAT_HOME></code></li> | |
| <li>Edit your <code><PLUTO_HOME>/build.properties</code> 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/apache-tomcat.5.0.27</code>, | |
| <code>c:\\apache-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 <code><PLUTO_HOME></code> issue the command: | |
| <code>maven fullDeployment</code></li> | |
| <li>Startup the server by using the appropriate Tomcat startup | |
| script located at <code><PLUTO_HOME>/bin</code>. | |
| For *nix use <code>startup.sh</code>; for windows use | |
| <code>startup.bat</code>.</li> | |
| <li>Point your browser to | |
| <code>http://localhost:8080/pluto/portal</code>, the Pluto Driver, | |
| and your ready to go!</li> | |
| </ul> | |
| </p> | |
| </subsection> | |
| </section> | |
| <section name="Installing Portlets"> | |
| <subsection name="Installing with Maven"> | |
| <p> | |
| <span style="color: #FF0000;">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.</span> | |
| </p> | |
| <p> | |
| In order to deploy a portlet application to pluto, you must follow the | |
| steps below: | |
| </p> | |
| <p> | |
| <b>Step 1:</b> Assemble your portlet application into a valid war. | |
| </p> | |
| <p> | |
| <b>Step 2:</b> Run the maven deploy goal on your war. This can be done | |
| by running this command line in the deploy subdirectory: | |
| <source><![CDATA[ | |
| maven deploy -Ddeploy=/MyPathToMyPortlet/target/MyPortlet.war | |
| ]]></source> | |
| See the <a href="developer/build_source.html">Building From Source</a> | |
| document for detailed instructions. | |
| </p> | |
| <p> | |
| Alternatively, there is an interactive ant script in the | |
| <code>portlet-deploy</code> directory that will perform the same task | |
| as the Maven deployment goal. | |
| </p> | |
| <p> | |
| <b>Step 3:</b> Modify the Portlet Entity Registry and the Page | |
| Registry and Portlet Contexts files. These configuration files are | |
| located at: | |
| <ul> | |
| <li><code>[portal-home]/WEB-INF/data/portletentityregistry.xml</code></li> | |
| <li><code>[portal-home]/WEB-INF/data/pageregistry.xml</code></li> | |
| <li><code>[portal-home]/WEB-INF/data/portletcontexts.txt</code></li> | |
| </ul> | |
| </p> | |
| <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> | |
| <p> | |
| <source><![CDATA[ | |
| <application id="6"> | |
| <definition-id>MyPortlet</definition-id> | |
| <portlet id="1"> | |
| <definition-id>MyPortlet.MyPortlet</definition-id> | |
| </portlet> | |
| </application> | |
| ]]></source> | |
| </p> | |
| <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> | |
| <p> | |
| <source><![CDATA[ | |
| <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> | |
| ... ... | |
| </fragment> | |
| ]]></source> | |
| </p> | |
| <p> | |
| The Portlet Contexts file (<code>portletcontexts.txt</code>) 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 <code><TOMCAT_HOME>/conf/Catalina/localhost</code> | |
| (or another 'conf' subdirectory). | |
| </p> | |
| </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 Application requires the following steps: | |
| <ul> | |
| <li>Assemble your portlet application into a valid war.</li> | |
| <li>Start Pluto and navigate to | |
| <code>http://localhost:8080/pluto/portal</code>, the local Pluto | |
| home page.</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> | |
| <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> | |