<?xml version="1.0" encoding="UTF-8"?> | |
<!-- | |
Copyright 2004 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>Getting Started With Pluto</title> | |
<author email="ddewolf@apache.org">David DeWolf</author> | |
<author email="zheng.at.apache.D0T.org">ZHENG Zhong</author> | |
<author email="cdoremus@apache.org">Craig Doremus</author> | |
</properties> | |
<body> | |
<section name="Installing the Pluto 1.1 Binary Build"> | |
<ol> | |
<li>Download a Pluto 1.1 binary distribution from | |
a <a href="http://cvs.apache.org/dist/portals/pluto/v1.1.0-beta2/">distribution site</a>.</li> | |
<li>Unzip the binary distribution into a directory.</li> | |
<ol> | |
<li><PLUTO-1.1-HOME> will be the top level directory.</li> | |
</ol> | |
<li>Execute startup.bat (Windows) or startup.sh (Unix) | |
in <PLUTO-1.1-HOME>/bin.</li> | |
<ol> | |
<li>Use shutdown.bat/shutdown.sh to stop the portal</li> | |
</ol> | |
<li>Browse to <a href="http://localhost:8080/pluto/portal">http://localhost:8080/pluto/portal</a></li> | |
<li>Login as the user pluto (password=pluto).</li> | |
</ol> | |
</section> | |
<section name="Building Pluto from Source"> | |
<p> | |
Maven 2 is utilized as the project management and build system for | |
Pluto 1.1. Pluto currently provides Maven plugins which can be used to | |
install the Pluto Portal, assemble portlet applications, deploy | |
applications, and publish portlet applications to the Pluto Portal. | |
</p> | |
<subsection name="Obtaining Pluto 1.1 Source Code"> | |
<p>The Pluto project uses the | |
<a href="http://subversion.tigris.org/">Subversion</a> version control | |
system. If you're new to Subversion, you can check out the | |
<a href="http://svnbook.red-bean.com/">online book</a> about Subversion. | |
Note that we are currently using Subversion 1.3.x (there are separate | |
versions of the book covering the different versions of Subversion). | |
</p> | |
<p><b>Web Access to Subversion</b></p> | |
<p> | |
To browse the Pluto 1.1 source code, you can use the | |
<a href="http://svn.apache.org/viewcvs.cgi/portals/pluto/trunk?root=Apache-SVN">ViewCVS | |
web interface</a> to Subversion. This is current at all times. | |
</p> | |
<p><b>Normal Subversion Access</b></p> | |
<p>Anyone can check code out of Subversion anonymously. However, you need to specify a | |
username and password in order to update the Subversion repository, and only | |
Pluto committers have the permissions to do that. We run Subversion | |
over standard HTTPS, so hopefully you won't have problems with intervening | |
firewalls.</p> | |
<h3>Check out from Subversion</h3> | |
<p>Again, anyone can do this. To check out the latest distribution of Pluto 1.1 (trunk) to a directory | |
called 'pluto' use this command: | |
<pre>svn checkout https://svn.apache.org/repos/asf/portals/pluto/trunk/ pluto</pre> | |
</p> | |
<p>To check out Pluto 1.1.0-beta2 source to the 'pluto' directory use this command: | |
<pre>svn checkout https://svn.apache.org/repos/asf/portals/pluto/tags/release-1.1.0-beta2/ pluto</pre> | |
</p> | |
<p> | |
Zipped up Pluto source distributions can also be downloaded from | |
a <a href="http://www.apache.org/dyn/closer.cgi/portals/pluto/">distribution mirror</a>. | |
</p> | |
</subsection> | |
<subsection name="Building Pluto with Maven 2"> | |
<p> | |
<code><PLUTO-1.1-SRCHOME></code> is the local directory where the | |
Pluto 1.1 source distribution has been checked out or unzipped into. | |
</p> | |
<p> | |
<source><![CDATA[ | |
$> cd <PLUTO-1.1-SRCHOME> | |
$> mvn install | |
$> mvn pluto:install -DinstallDir=path/to/appserver | |
]]></source> | |
</p> | |
<p> | |
The <code>install</code> goal is a built in Maven 2 lifecycle | |
which builds the project artifacts and installs them into the Maven | |
repository. | |
</p> | |
<p> | |
The <code>pluto:install</code> goal will take the resulting artifacts | |
and properly deploy them within the configured Tomcat installation. | |
Currently, the Pluto 1.1 install has been tested on Tomcat 5.5.9 and Tomcat 5.5.17. | |
The Tomcat 5 archive can be found <a href="http://archive.apache.org/dist/tomcat/tomcat-5/archive">here</a>. | |
</p> | |
<p> | |
If installing to a directory that contains spaces, <code>installDir</code> | |
needs to be enclosed within quotes: | |
</p> | |
<p> | |
<source><![CDATA[ | |
C:\pluto> mvn pluto:install -DinstallDir="C:\Program Files\Apache Software Foundation\Tomcat 5.5" | |
]]></source> | |
</p> | |
</subsection> | |
<subsection name="Installing Pluto Manually"> | |
<p> | |
This section documents the manual installation of Pluto into Tomcat. It replaces | |
the pluto:install goal, but requires that the built-in Maven 2 install goal | |
(<code>mvn install</code>) be run from <code><PLUTO-1.1-SRCHOME></code>. | |
</p> | |
<p> | |
<b>Step 1:</b> | |
<source><![CDATA[ | |
$> cd <PLUTO-1.1-SRCHOME> | |
$> mvn install | |
]]></source> | |
</p> | |
<p> | |
<b>Step 2:</b> Copy the following to | |
<code><TOMCAT_HOME>/shared/lib</code>: | |
<ul> | |
<li>castor-1.0.jar</li> | |
<li>portlet-api-1.0.jar</li> | |
<li>pluto-container-1.1-beta2.jar</li> | |
<li>pluto-descriptor-api-1.1-beta2.jar</li> | |
<li>pluto-descriptor-impl-1.1-beta2.jar</li> | |
<li>pluto-taglib-1.1.0-beta2.jar</li> | |
</ul> | |
</p> | |
<p> | |
<b>Step 3:</b> Copy the following to | |
<code><TOMCAT_HOME>/common/endorsed</code>: | |
<ul> | |
<li>xercesImpl-2.6.2.jar</li> | |
<li>xmlParserAPIs-2.6.2.jar</li> | |
</ul> | |
</p> | |
<p> | |
<b>Step 4:</b> Copy the following to | |
<code><TOMCAT_HOME>/conf/Catalina/localhost</code>: | |
<ul> | |
<li><PLUTO_SRCHOME>/pluto-portal/src/main/resources/pluto.xml</li> | |
<li><PLUTO_SRCHOME>/pluto-testsuite/src/main/resources/testsuite.xml</li> | |
</ul> | |
</p> | |
<p> | |
<b>Step 5:</b> Copy the following to | |
<code><TOMCAT_HOME>/webapps</code>: | |
<ul> | |
<li><PLUTO_SRCHOME>/pluto-portal/target/pluto-portal.war</li> | |
<li><PLUTO_SRCHOME>/pluto-testsuite/target/pluto-testsuite.war</li> | |
</ul> | |
</p> | |
</subsection> | |
<subsection name="Installing Pluto with a Windows EXE"> | |
<p> | |
The NSIS Installer is not yet complete, but we hope to have a fully | |
functional one soon. Anyone is more than welcome to assist us in | |
this process. | |
</p> | |
</subsection> | |
<subsection name="Configuring Source-Built Pluto for Application Scope PortletSession Attributes"> | |
<p>To be able to use application-scoped <code>PortletSession</code> attributes in Pluto, modify | |
the Connector element for port 8080 in <code><TOMCAT_HOME>/conf/server.xml</code> by | |
adding the following attribute and value: emptySessionPath="true". | |
</p> | |
</subsection> | |
<subsection name="Configuring User and Role in the Pluto Source Build"> | |
<p> | |
The Pluto Testsuite portlet application needs the role '<code>pluto</code>' | |
to run the Security Mapping Test. So before starting tomcat, you should | |
edit <code><TOMCAT_HOME>/conf/tomcat-users.xml</code>, add the | |
role '<code>pluto</code>', and add a user in that role. The simplest way | |
to do this is to edit add the '<code>pluto</code>' role to the | |
'<code>tomcat</code>' user's record. Here is a sample | |
<code>tomcat-users.xml</code> file: | |
<source><![CDATA[ | |
<?xml version="1.0" encoding="utf-8"?> | |
<tomcat-users> | |
<role rolename="pluto"/> | |
<role rolename="tomcat"/> | |
<role rolename="role1"/> | |
<user username="tomcat" password="tomcat" roles="tomcat,pluto"/> | |
<user username="role1" password="tomcat" roles="role1"/> | |
<user username="both" password="tomcat" roles="tomcat,role1"/> | |
</tomcat-users> | |
]]></source> | |
</p> | |
</subsection> | |
<subsection name="Starting the Portal"> | |
<p> | |
Now you are ready to use the Pluto Portal built from source. Start up tomcat by running | |
<code>startup.bat</code> (for windows) or <code>startup.sh</code> (for | |
*nix) in <code><TOMCAT_HOME>/bin</code>, and browse to | |
<code>http://localhost:8080/pluto/portal</code>. Login to Pluto using | |
the user and password you just created in <code>tomcat-users.xml</code>. | |
If you added the 'pluto' role to the 'tomcat' user's record, you can | |
login as 'tomcat/tomcat'. | |
</p> | |
</subsection> | |
</section> | |
</body> | |
</document> | |