You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@roller.apache.org by sn...@apache.org on 2007/07/07 17:40:07 UTC
svn commit: r554222 [2/5] - in /roller/trunk/apps/weblogger/docs: ./
installguide/ installguide/generated/
Modified: roller/trunk/apps/weblogger/docs/installguide/generated/roller-install-guide.html
URL: http://svn.apache.org/viewvc/roller/trunk/apps/weblogger/docs/installguide/generated/roller-install-guide.html?view=diff&rev=554222&r1=554221&r2=554222
==============================================================================
--- roller/trunk/apps/weblogger/docs/installguide/generated/roller-install-guide.html (original)
+++ roller/trunk/apps/weblogger/docs/installguide/generated/roller-install-guide.html Sat Jul 7 08:40:06 2007
@@ -1,827 +1,752 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
- <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+ <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE></TITLE>
- <META NAME="GENERATOR" CONTENT="OpenOffice.org 2.0 (Solaris x86)">
- <META NAME="AUTHOR" CONTENT="Dave Johnson">
- <META NAME="CREATED" CONTENT="20060123;11164600">
- <META NAME="CHANGEDBY" CONTENT="Dave Johnson">
- <META NAME="CHANGED" CONTENT="20070302;9530400">
- <STYLE>
+ <META NAME="GENERATOR" CONTENT="NeoOffice 2.1 (Unix)">
+ <META NAME="CREATED" CONTENT="20070706;11182000">
+ <META NAME="CHANGED" CONTENT="20070707;11310200">
+ <META NAME="KEYWORDS" CONTENT="OpenDS Directory Server Administration Framework">
+ <STYLE TYPE="text/css">
<!--
- @page { size: 8.5in 11in; margin: 0.5in }
- P { margin-bottom: 0.08in }
- P.western { font-family: "Times New Roman" }
- H2.western { font-family: "Times New Roman" }
- H2.cjk { font-family: "Andale Sans UI" }
- H2.ctl { font-family: "Lucidasans" }
- H3.western { font-family: "Times New Roman" }
- H3.cjk { font-family: "Andale Sans UI" }
+ P { margin-bottom: 0.08in; widows: 2; orphans: 2 }
+ P.western { font-family: "Times New Roman", serif }
+ H1 { margin-bottom: 0.08in; border-top: none; border-bottom: 2.50pt solid #000000; border-left: none; border-right: none; padding: 0in; widows: 2; orphans: 2; page-break-before: always }
+ H1.western { font-family: "Helvetica", sans-serif; font-size: 22pt; font-style: italic }
+ H1.cjk { font-family: "Mincho"; font-size: 16pt }
+ H1.ctl { font-family: "Lucidasans"; font-size: 16pt }
+ H2 { margin-bottom: 0.08in; widows: 2; orphans: 2 }
+ H2.western { font-family: "Helvetica", sans-serif; font-style: italic }
+ H2.cjk { font-family: "Mincho"; font-size: 14pt; font-style: italic }
+ H2.ctl { font-family: "Lucidasans"; font-size: 14pt; font-style: italic }
+ H3 { margin-bottom: 0.08in; widows: 2; orphans: 2 }
+ H3.western { font-family: "Helvetica", sans-serif; font-size: 16pt }
+ H3.cjk { font-family: "Mincho" }
H3.ctl { font-family: "Lucidasans" }
- H4.western { font-family: "Times New Roman"; font-size: 13pt }
- H4.cjk { font-family: "Andale Sans UI" }
- H4.ctl { font-family: "Lucidasans" }
- PRE { font-family: "Cumberland", monospace }
+ TD P { margin-bottom: 0in; widows: 2; orphans: 2 }
+ TD P.western { font-family: "Times New Roman", serif }
+ TH P { margin-bottom: 0in; border-top: none; border-bottom: 2.50pt solid #000000; border-left: none; border-right: none; padding: 0in; widows: 2; orphans: 2 }
+ TH P.western { font-family: "Helvetica", sans-serif; font-style: oblique }
+ TH P.cjk { font-style: italic }
+ TH P.ctl { font-style: italic }
+ PRE { font-family: "Cumberland", monospace; widows: 2; orphans: 2 }
+ H3.heading-4-western { font-family: "Helvetica Bold", sans-serif; font-style: italic; page-break-before: auto }
+ H3.heading-4-cjk { font-family: "Andale Sans UI"; font-size: 12pt; page-break-before: auto }
+ H3.heading-4-ctl { font-family: "Lucidasans"; font-size: 12pt; page-break-before: auto }
TT { font-family: "Cumberland", monospace }
-->
</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=RIGHT STYLE="margin-bottom: 0in; background: transparent">
+<IMG SRC="roller-install-guide_html_m3d0892e2.png" NAME="graphics1" ALIGN=BOTTOM WIDTH=210 HEIGHT=85 BORDER=0></P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=7 STYLE="font-size: 40pt"><B>Installation
-Guide</B></FONT></P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=7 STYLE="font-size: 32pt"><B>Apache
-Roller</B></FONT></P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><A NAME="DDE_LINK1"></A>
-<FONT SIZE=7 STYLE="font-size: 32pt"><B>Version 3.2</B></FONT></P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=RIGHT STYLE="margin-bottom: 0in; background: transparent">
+<FONT FACE="Helvetica, sans-serif"><FONT SIZE=7><B>Installation Guide</B></FONT></FONT></P>
+<P CLASS="western" ALIGN=RIGHT STYLE="margin-bottom: 0in; background: transparent">
+<FONT FACE="Helvetica, sans-serif"><FONT SIZE=7><B><SPAN STYLE="background: #ffff00">DRAFT
+20070707</SPAN></B></FONT></FONT></P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" ALIGN=LEFT><FONT FACE="Courier New"><FONT SIZE=1 STYLE="font-size: 8pt"><I>Licensed
-to the Apache Software Foundation (ASF) under one or more contributor
-license agreements. The ASF licenses this file to You 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</I></FONT></FONT></P>
-<P CLASS="western" ALIGN=LEFT>
-<FONT FACE="Courier New"><FONT SIZE=1 STYLE="font-size: 8pt"><I>http://www.apache.org/licenses/LICENSE-2.0</I></FONT></FONT></P>
-<P CLASS="western" ALIGN=LEFT><FONT FACE="Courier New"><FONT SIZE=1 STYLE="font-size: 8pt"><I>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. For additional
-information regarding copyright in this work, please see the NOTICE
-file in the top level directory of this distribution.</I></FONT></FONT></P>
-<P CLASS="western" ALIGN=LEFT STYLE="page-break-before: always"><BR><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<FONT FACE="Helvetica, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Apache
+Roller Weblogger</B></FONT></FONT></P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<FONT FACE="Helvetica, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Version
+4.0</B></FONT></FONT></P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<SDFIELD TYPE=DOCINFO SUBTYPE=CHANGE FORMAT=DATE SDNUM="1033;1033;MMMM YYYY">July 2007</SDFIELD></P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
<DIV ID="Table of Contents1" DIR="LTR">
<DIV ID="Table of Contents1_Head" DIR="LTR">
- <P STYLE="margin-top: 0.17in; margin-bottom: 0.2in; page-break-after: avoid">
- <FONT FACE="Albany, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Table
+ <P STYLE="margin-top: 0.17in; page-break-before: always; page-break-after: avoid">
+ <FONT FACE="Helvetica, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Table
of Contents</B></FONT></FONT></P>
</DIV>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Introduction 4</B></FONT></P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 1: Before you install Roller 5</B></FONT></P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 2: Unpack the Roller distribution 6</B></FONT></P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">UNIX example 6</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Windows example 6</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Roller
- distribution layout 6</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">The ROLLER
- environment variable 6</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 3: Install required third party jars 7</B></FONT></P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 3.1:
- Download and install Hibernate 7</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 3.2: Install
- JDBC driver jar(s) 7</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">UNIX example 7</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Windows example 7</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">NOTES 7</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 3.3: Install
- JavaMail and Activation jars 9</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">UNIX example 9</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Windows example 9</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">NOTES 9</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 4: Create Roller tables in your database 10</B></FONT></P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">UNIX example 10</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Windows
- example 10</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 5: Deploy Roller to your application server 12</B></FONT></P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 6: Check your internationalization settings 14</B></FONT></P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Check your
- application server's URI encoding setting! 14</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 7: Setup Roller data directories 15</B></FONT></P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.1: Create
- uploads directory 15</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.2: Create
- search-index directory 15</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.3: Create
- planet-cache directory (optional) 15</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.4: Make
- sure that the logs subdirectory exists 15</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 8: Review Roller configuration 16</B></FONT></P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 8.1: Review
- the WEB-INF/classes/roller.properties file 16</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Where to define
- custom properties 16</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">What properties
- you should set 16</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 8.2: Change
- keys in the WEB-INF/security.xml file 17</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 8.3: Verify
- the database dialet setting in the Hibernate configuration file 17</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
- 9: Start Tomcat and start using Roller 18</B></FONT></P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">UNIX example 18</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">Windows
- example 18</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">You're done! 18</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Appendix
- A: Upgrading an existing Roller installation 19</B></FONT></P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">Important notes
- about Roller 3.0 19</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">UPGRADE STEP 1:
- Shutdown and backup your old Roller 20</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">UPGRADE STEP 2:
- Install the new Roller 20</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">UPGRADE STEP 3:
- Copy resources and update configs 20</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">3.1 Copy your old
- resources and other files you've added 20</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">3.2 Remove
- JavaMail jars if duplicated 20</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">3.3 Review
- configuration properties 21</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">UPGRADE STEP 4:
- Upgrade the database 21</P>
- <P STYLE="margin-left: 0.39in; margin-bottom: 0in">UPGRADE STEP 5:
- Startup your app server 21</P>
- <P STYLE="margin-left: 0.59in; margin-bottom: 0in">And you're done!
- 21</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Appendix
- B: The WEB-INF/roller.properties file 23</B></FONT></P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>1 Overview 3</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">1.1 Copyright
+ and trademark information 3</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">1.2 Feedback 3</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">1.3
+ Acknowledgments 3</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">1.4
+ Modifications and Updates 3</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>2 The 5-minute
+ install 4</B></FONT></P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>3 Ready to roll? 5</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">3.1 Tomcat:
+ JavaMail and Activation 5</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">3.2 Tomcat: URI
+ encoding needed for I118N 5</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>4 Download and
+ un-package Roller 6</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">4.1 Installation
+ directory layout 6</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">4.2 The Roller
+ Weblogger WAR 6</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>5 Prepare your
+ database for Roller 7</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">5.1 Create a
+ database for Roller 7</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">5.2 Check your
+ JDBC driver setup 7</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">5.3 MySQL and
+ Oracle considerations 7</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>6 Configure Roller 8</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">6.1 MySQL
+ example 8</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>7 Deploy Roller 9</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">7.1 Put
+ roller-custom.properties in classpath 9</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">7.2 Deploy
+ Roller via administration console 9</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>8 Getting started
+ with Roller 10</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">8.1 Navigate to
+ Roller and finish the install 10</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">8.2 Register a
+ user and create a weblog 10</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>9 Configuration tips
+ and tricks 12</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">9.1 Setting up
+ Roller's Planet feed aggregator 12</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">9.2 Changing
+ keys in security.xml 13</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">9.3 Using
+ Server-provided database and mail resources 14</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">9.4 Manual table
+ creation and upgrade 15</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>10 Upgrading
+ Roller 16</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">10.1 For those
+ upgrading from Roller 2.x to Roller 4.0 16</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">10.2 Backup your
+ old Roller 17</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in">10.3 Install and
+ startup the new Roller 18</P>
+ <P STYLE="margin-bottom: 0in"><FONT SIZE=3><B>11
+ roller.properties 19</B></FONT></P>
</DIV>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western"><BR><BR>
</P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-Introduction"></A>
-Introduction</H2>
-<P CLASS="western"><B>This document describes how to install Roller
-in the following environment: </B>
+<H1 CLASS="western" STYLE="page-break-before: always">1Overview</H1>
+<P CLASS="western" ALIGN=LEFT STYLE="background: transparent; font-weight: medium">
+This document describes how to install the Apache Roller Weblogger
+software. It explains what you need to install first, how to download
+Roller, how to configure Roller and how to install it to your
+existing Java application server and relational database. If also
+offers a 5-minute install option for more advanced folks.</P>
+<H2 CLASS="western">1.1Copyright and trademark information</H2>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+The contents of this document are subject to the terms of the Apache
+Software License.</P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<UL>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in; font-weight: medium">
- Operating System: UNIX or Windows based operating system
- </P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in; font-weight: medium">
- Java development kit: Java 2 SE 1.4 SDK (or later)</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in; font-weight: medium">
- Application server: Tomcat 5.X (or later)</P>
- <LI><P CLASS="western" STYLE="font-weight: medium">Relational
- Database: MySQL 4.X (or later)</P>
-</UL>
-<P CLASS="western"><BR><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+All trademarks within this document belong to legitimate owners.</P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western"><B>NOTE: If you're upgrading from an earlier
-release of Roller, read Appendix A first</B></P>
-<P CLASS="western"><BR><BR>
+<H2 CLASS="western">1.2Feedback</H2>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+Please direct any comments or suggestions about this document to:
+user@roller.apache.org</P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western"><B>What do you need to know to install Roller? </B>You
-need to know how to use the UNIX or Windows command-line, how to set
-environment variables, how to create a database in MySQL and how to
-start and stop Tomcat.</P>
-<P CLASS="western"><B>What about other servlet containers?</B> <SPAN STYLE="font-style: normal">These
-instructions target Tomcat, but you should be able to make Roller
-work with just about any standard Servlet 2.3 compatible application
-server. For full support of Roller's internationalization features,
-we recommend Servlet 2.4. If you deploy Roller to a non-Tomcat
-server, please contribute your install notes to help others who might
-want to do the same.</SPAN>
-</P>
-<P CLASS="western"><B>What about other databases?</B> These
-instructions target MySQL, but Roller also includes database setup
-scripts for PostgreSQL 7.X later, Apache Derby, IBM DB2, Oracle and
-HSQL-DB.</P>
-<P CLASS="western"><B>What platform combinations are known to work?</B>
-For information on which platforms we can vouch for, see the the
-<SPAN STYLE="font-weight: medium"><I>Platforms</I></SPAN> page on the
-Roller wiki.</P>
-<P CLASS="western"><BR><BR>
+<H2 CLASS="western">1.3Acknowledgments</H2>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+The original version of this document was written by Dave Johnson.
+The document is currently written and updated by the Apache Roller
+project of the Apache Software Foundation.</P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+The general format of this document was based on the documentation
+template used by the OpenDS project which in turn was based on the
+templates used by the <A HREF="http://www.OpenOffice.org/">OpenOffice.org</A>
+project.</P>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP1Prerequisites1"></A><A NAME="ref-InstallationGuide_2.x-1"></A>
-STEP 1: Before you install Roller</H2>
-<P CLASS="western" STYLE="font-weight: medium">Before you install
-Roller software you should install and configure the Java development
-kit, your application server and your database.</P>
-<P CLASS="western">As part of the Tomcat install you should have set
-the environment variable CATALINA_HOME to point to your Tomcat
-installation directory. If not, you might want to set it now because
-we will refer to it in this installation guide. Below are some
-examples that show how to set this variable. Make sure you substitute
-the right path to your Tomcat installation.</P>
-<P CLASS="western">For UNIX with bash shell:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> %
-export CATALINA_HOME=/opt/jakarta-tomcat-5.5.9</FONT></FONT></P>
-<P CLASS="western"><BR><BR>
+<H2 CLASS="western">1.4Modifications and Updates</H2>
+<TABLE WIDTH=100% BORDER=1 BORDERCOLOR="#000000" CELLPADDING=4 CELLSPACING=0 RULES=COLS STYLE="page-break-inside: avoid">
+ <COL WIDTH=59*>
+ <COL WIDTH=197*>
+ <THEAD>
+ <TR VALIGN=TOP>
+ <TH WIDTH=23%>
+ <P CLASS="western" ALIGN=LEFT>Date</P>
+ </TH>
+ <TH WIDTH=77%>
+ <P CLASS="western" ALIGN=LEFT>Description of Change</P>
+ </TH>
+ </TR>
+ </THEAD>
+ <TBODY>
+ <TR VALIGN=TOP>
+ <TD WIDTH=23%>
+ <P CLASS="western" ALIGN=LEFT>July 2007</P>
+ </TD>
+ <TD WIDTH=77%>
+ <P CLASS="western" ALIGN=LEFT>Rewritten for simplified Roller 4.0
+ installation process</P>
+ </TD>
+ </TR>
+ </TBODY>
+</TABLE>
+<P CLASS="western" ALIGN=LEFT STYLE="margin-bottom: 0in; background: transparent">
+<BR>
</P>
-<P CLASS="western">For UNIX with c-shell:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> %
-setenv CATALINA_HOME /opt/jakarta-tomcat-5.5.9</FONT></FONT></P>
+<H1 CLASS="western" STYLE="page-break-before: always">2The 5-minute
+install</H1>
+<P CLASS="western">If you really know what you're doing, you just
+want to get Roller up-and-running for a quick evaluation and you are
+using a well-supported platform (e.g. Tomcat and MySQL), you can
+probably get up and running in about 5-minutes by following the
+simple instructions on this page. If you're not so confident, then
+skip this page and go on to <B>Section 3</B>. Here's what you do for
+the 5-minute install:</P>
<P CLASS="western"><BR><BR>
</P>
-<P CLASS="western">For Windows with DOS shell</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> C>
-set CATALINA_HOME d:\jakarta-tomcat-5.5.9</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western"><B>NOTES</B></P>
-<UL>
- <LI><P CLASS="western">For MySQL, make sure you enable UTF-8
- support. See the page Setting Up UTF-8 on MySQL page on the Roller
- wiki for details.</P>
- <LI><P CLASS="western">For MySQL, make sure that TCP/IP networking
- is enabled. In some versions of MySQL, this option is off by
- default. See the page Debian MySQL for details. The Connector/J JDBC
- driver can only access MySQL via TCP/IP.
- </P>
-</UL>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western"><B>STEP 1: Download Roller</B> and un-package into
+a directory on your disk via Zip or GNU Tar.</P>
+<P CLASS="western"><B>STEP 2: Create a database for the Roller
+tables</B>. <BR>For exmaple, on MySQL you might do something like
+this:</P>
+<PRE> <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">% mysql -u root -p</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">password: *****</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">mysql> create database rollerdb;</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">mysql> grant all on rollerdb.* to scott@'%' identified by 'tiger';</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">mysql> grant all on rollerdb.* to scott@localhost identified by 'tiger';</FONT></FONT></PRE><P CLASS="western">
+<BR><BR>
</P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP2UnpackTheDownloadedZIPOrTARFile2"></A>
-STEP 2: Unpack the Roller distribution</H2>
-<P CLASS="western">Pick a directory on your computer and unpack the
-Roller distribution using either GNU tar on UNIX or WinZip on
-Windows. Here are some examples to show you how you might unpack
-Roller on your computer.</P>
-<H4 CLASS="western">UNIX example</H4>
-<P CLASS="western">Assuming you download the distribution into your
-home directory and you'd like to install Roller into <FONT FACE="Courier New">/usr/local</FONT>
-you might do something like this in the bash shell:</P>
-<PRE><FONT FACE="Courier New"><FONT SIZE=3> % cd /usr/local</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=3> % tar xzvf ~/apache-roller-3.2.tar.gz</FONT></FONT>
+<P CLASS="western"><B>STEP 3: Create a roller-custom.properties</B>
+file in your Servlet container's classpath, e.g. on Tomcat you'd put
+it in <FONT FACE="Courier New, monospace">common/classes</FONT>. Put
+the settings below into the file and substitute your database and
+mail connection parameters for those in bold.</P>
+<PRE> <FONT SIZE=2 STYLE="font-size: 11pt">installation.type=auto</FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">database.configurationType=jdbc</FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">database.jdbc.driverClass=<B><I>com.mysql.jdbc.Driver</I></B></FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">database.jdbc.connectionURL=<B><I>jdbc:mysql://localhost:3306/rollerdb</I></B></FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">database.jdbc.username=<B><I>scott</I></B></FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">database.jdbc.password=<B><I>tiger</I></B></FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">mail.configurationType=properties</FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">mail.hostName=</FONT><TT><B><I><FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New">smtp-server.example.com</FONT></FONT></I></B></TT>
+<TT> <FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New"><SPAN STYLE="font-weight: medium"><SPAN STYLE="font-style: normal">mail.username=</SPAN></SPAN><B><I>scott</I></B></FONT></FONT></TT>
+<TT> <FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New"><SPAN STYLE="font-weight: medium"><SPAN STYLE="font-style: normal">mail.password=</SPAN></SPAN><B><I>tiger</I></B></FONT></FONT></TT>
</PRE><P CLASS="western">
-That would create the Roller installation directory
-<FONT FACE="Courier New">/usr/local/apache-roller-3.2</FONT>.
-</P>
-<H4 CLASS="western">Windows example</H4>
-<P CLASS="western">You can Use WinZip to extract the Roller
-distribution file into the directory of your choice.
-</P>
-<H4 CLASS="western">Roller distribution layout</H4>
-<P CLASS="western">Once you've extracted the files you'll see that
-the Roller release contains two directories and a couple of text
-files:</P>
-<P CLASS="western"> docs Directory containing Roller documentation</P>
-<P CLASS="western"> webapp/roller Directory containing rhe Roller
-web application in WAR directory layout</P>
-<P CLASS="western"> README.txt Explains what Roller is</P>
-<P CLASS="western"> CHANGES.txt Lists changes made in each release</P>
-<P CLASS="western"> NOTICE.txt Copyright notices and credits</P>
-<P CLASS="western"> LICENSE.txt The Apache Software License</P>
-<H4 CLASS="western">The ROLLER environment variable</H4>
-<P CLASS="western">In this guide, we'll refer to the Roller web
-application directory using the ROLLER environment variable. In UNIX
-this will be $ROLLER. In Windows, it will be %ROLLER%. You don't <I>have</I>
-to set the ROLLER environment variable, we just use it to simplify
-the installation guide, but here's how you'd do it.</P>
-<P CLASS="western">UNIX example (assuming you installed into
-<FONT FACE="Courier New">/usr/local</FONT>):</P>
-<P CLASS="western"><FONT FACE="Courier New"> % set $ROLLER =
-/usr/local/apache-roller-3.2/webapp/roller</FONT></P>
-<P CLASS="western">Windows example (assuming you installed into <FONT FACE="Courier New">c:\</FONT>)</P>
-<P CLASS="western"><FONT FACE="Courier New"> % set %ROLLER% =
-c:\apache-roller-3.2/webapp/roller</FONT></P>
-<P CLASS="western"><A NAME="DDE_LINK3"></A><BR><BR>
-</P>
-<H2 CLASS="western"></H2>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP4DownloadAndInstallRequiredJars4"></A>
-STEP 3: Install required third party jars</H2>
-<P CLASS="western">You also need to download and install some
-third-party jars, jars that we can't include in Roller due to
-licensing restrictions. These are the JDBC driver, JavaMail and
-Activation jars.</P>
-<H3 CLASS="western"><A NAME="DDE_LINK4"></A>STEP 3.1: Download and
-install Hibernate</H3>
-<P CLASS="western"><A NAME="DDE_LINK"></A>Roller <I>requires</I>
-<B>Hibernate Version 3.1.2</B>, which you must download separately
-from Roller.
-</P>
-<P CLASS="western"> Download Hibernate 3.1.2 from SourceForge</P>
-<P CLASS="western"> <A HREF="http://prdownloads.sourceforge.net/hibernate/hibernate-3.1.2.tar.gz">http://prdownloads.sourceforge.net/hibernate/hibernate-3.1.2.tar.gz</A></P>
-<P CLASS="western">Copy the following files from Hibernate into the
-Roller WEB-INF/lib directory:</P>
-<UL>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">hibernate3.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">asm-attrs.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">asm.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">cglib-2.1.3.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">dom4j.1.6.1.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">ehcache-1.1.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">jdbc2_0-stdext.jar</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">jta.jar</P>
-</UL>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
+<B>STEP 4: Check your Servlet container's JDBC and JavaMail setup.
+</B><SPAN STYLE="font-weight: medium">Make sure you've got the JDBC
+driver for your database in your Servlet container's classpath, e.g.
+on Tomcat place the driver JAR in <FONT FACE="Courier New, monospace">common/lib</FONT>.
+And on Tomcat, if you want to be able to send mail you'll need to add
+the JavaMail and Activation jars (<FONT FACE="Courier New, monospace">mail.jar</FONT>
+and <FONT FACE="Courier New, monospace">activation.jar</FONT>) there
+too.</SPAN></P>
+<P CLASS="western"><B>STEP 5: Deploy Roller to your Servlet container</B>
+using your container's Admin Console deploy Roller as a directory.
+The Roller WAR directory is in the installation directory under
+<FONT FACE="Courier New, monospace">webapp/roller</FONT>.</P>
+<P CLASS="western"><B>STEP 6: Browse to Roller and get Rollin'</B>
+(probably at <A HREF="http://localhost:8080/roller">http://localhost:8080/roller</A>).
+If Roller is up and running, then proceed to Section 8 Getting
+started with Roller. If Roller isn't up and running and you can 't
+figure out why, then try the normal installation procedure starting
+with <B>Section 3</B> below.
</P>
-<P CLASS="western">The Roller Support project at Java.Net offers some
-bundles that might make this part of the installation easier. Visit
-<A HREF="http://roller.dev.java.net/">http://roller.dev.java.net</A>
-for more information.</P>
-<H3 CLASS="western">STEP 3.2: Install JDBC driver jar(s)</H3>
-<P CLASS="western"><FONT FACE="Times New Roman">Download the JDBC
-driver jar for your database and put it in the classpath of your
-application server. For example, assuming Tomcat and MySQL, you'd
-download the J/Connector JDBC driver from mysql.com and you'd place
-it in the Tomcat common/lib directory.</FONT></P>
-<H4 CLASS="western">UNIX example</H4>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> %
-cp mysql-connector.jar $CATALINA_HOME/common/lib</FONT></FONT></P>
-<H4 CLASS="western">Windows example</H4>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> C>
-copy mysql-connector.jar %CATALINA_HOME%\common\lib</FONT></FONT></P>
-<H4 CLASS="western">NOTES</H4>
-<UL>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">For MySQL 4.1.X
- users, we recommend that you use the J/Connector 3.0.X JDBC drivers
- instead of the newer 3.1.X series. If you <I>must</I> use
- J/Connector/J 3.1.X then please read <I>Installation FAQ</I> page
- item #13 on the Roller wiki.</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">For MySQL 5.X
- users, we recommend that you use the J/Connector 3.1.X JDBC drivers
- instead of the newer 3.1.X series, you'll also need to change the
- Hibernate configuration file to use the MySQL5 dialect (see Section
- 8.3 for details on that).</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in"><A NAME="st"></A>For
- Oracle users, we recommend that you use the 10g (<A HREF="http://10.1.0.2/" TARGET="_blank">10.1.0.2</A>
- or higher) drivers which should<BR>be packaged as ojdbc14.jar --
- even if operating on Oracle 9 server.</P>
-</UL>
<P CLASS="western"><BR><BR>
</P>
-<H3 CLASS="western" STYLE="page-break-before: always">STEP 3.3:
-Install JavaMail and Activation jars</H3>
-<P CLASS="western">If you like to use Roller's e-mail notification
-features, you'll need to add the JavaMail and Activation jars to your
-application server's classpath. Currently, we ship these jars with
-Roller, but you will need to <B>move</B> them from the Roller
-<FONT FACE="Courier New">WEB-INF/lib</FONT> directory and into the
-Tomcat <FONT FACE="Courier New">common/lib</FONT> directory, or your
-server's equivalent location.</P>
-<H4 CLASS="western">UNIX example</H4>
-<P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3> % mv
-$ROLLER/WEB-INF/lib/mail.jar $CATALINA_HOME/common/lib</FONT></FONT></P>
-<P CLASS="western"><FONT SIZE=2><FONT SIZE=3><FONT FACE="Courier New"> %
-mv $ROLLER/WEB-INF/lib/activation.jar $CATALINA_HOME/common/lib</FONT></FONT> </FONT></P>
-<H4 CLASS="western">Windows example</H4>
-<P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3> c> move
-%ROLLER%\WEB-INF\lib\mail.jar %CATALINA_HOME%\common\lib</FONT></FONT></P>
-<P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3> C> move
-%ROLLER%\WEB-INF\lib\activation.jar %CATALINA_HOME%\common\lib</FONT></FONT></P>
-<H4 CLASS="western">NOTES</H4>
-<UL>
- <LI><P CLASS="western">To enable the Roller's e-mail notification
- features, you'll also need to setup a mail session resource in your
- application server configuration file (see the next section) and
- you'll need to configure e-mail notification in the Roller UI.</P>
-</UL>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP3CreateRollerTablesInYourDatabase3"></A><A NAME="ref-InstallationGuide_2.x-3"></A>
-STEP 4: Create Roller tables in your database</H2>
-<P CLASS="western">Create a new database within your MySQL
-installation, create a user with all privileges within that database
-and run the Roller database creation script to create tables within
-that new database. Roller includes database creation scripts for a
-variety of database, but MySQL is the most widely used and best
-supported option. You can find the database creation scripts in the
-Roller webapp directory <FONT FACE="Courier New">$ROLLER/WEB-INF/dbscripts/<I><dbname></I></FONT>.
-Here's the list of scripts currently in Roller:</P>
+<H1 CLASS="western">3Ready to roll?</H1>
+<P CLASS="western">First, let's make sure you have everything you
+need to install and run Roller.</P>
+<P CLASS="western" ALIGN=LEFT>Roller is a database-driven Java web
+application. To run it you need Java, a Java Servlet container such
+as Tomcat and a database such as MySQL. More specifically, here's
+what you need to install and run Roller:</P>
<UL>
- <LI><P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3>WEB-INF/dbscripts/mysql/creatdb.sql </FONT></FONT></P>
- <LI><P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3>WEB-INF/dbscripts/postgresql/creatdb.sql </FONT></FONT></P>
- <LI><P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3>WEB-INF/dbscripts/hsqldb/creatdb.sql</FONT></FONT></P>
- <LI><P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3>WEB-INF/dbscripts/derby/creatdb.sql</FONT></FONT></P>
- <LI><P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3>WEB-INF/dbscripts/db2/creatdb.sql</FONT></FONT></P>
- <LI><P CLASS="western"><FONT FACE="Courier New"><FONT SIZE=3>WEB-INF/dbscripts/oracle/creatdb.sql</FONT></FONT></P>
+ <LI><P CLASS="western"><B>The Java development kit</B>, specifically
+ the Sun Java 2 SE 1.5 JDK. The computer on which you install Roller
+ should be configured to run with the Java SE 5. Roller 3.x was the
+ last major Roller release to support Java 1.4.2.</P>
+ <LI><P CLASS="western"><B>A Java application server</B>, or more
+ specifically a Servlet container that supports the Servlet 2.4 API.
+ Hereinafter, we'll just call this your <I>server</I>. The Roller
+ community tends to use and is best able to answer questions about
+ Tomcat 5.5, Tomcat 6.0, Sun Web Server 7.0 and Glassfish 2.0.
+ </P>
+ <LI><P CLASS="western"><B>A relational database</B> such as MySQL or
+ Apache Derby. The Roller community tends to use and is best able to
+ answer questions about MySQL and Apache Derby, but it is possible to
+ use other databases with Roller. Roller includes database creation
+ scripts for DB2, Derby, HSQL-DB, Microsoft SQL Server, MySQL, Oracle
+ and PostgreSQL.</P>
</UL>
-<P CLASS="western">Here are some examples to show you how you might
-create the Roller tables in MySQL:</P>
-<H4 CLASS="western">UNIX example</H4>
-<PRE><FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> % cd $ROLLER/WEB-INF/dbscripts/mysql</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> % mysql -u root -p</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> password: *****</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> create database roller;</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> grant all on roller.* to scott@'%' identified by 'tiger';</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> grant all on roller.* to scott@localhost identified by 'tiger';</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> use roller;</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> source createdb.sql</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> quit</FONT></FONT></PRE><H4 CLASS="western">
-Windows example</H4>
-<PRE><FONT SIZE=2 STYLE="font-size: 11pt"> <FONT FACE="Courier New">C> cd %ROLLER%\WEB-INF\dbscripts\mysql</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> C> mysql -u root -p</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> password: *****</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> create database roller;</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> grant all on roller.* to scott@'%' identified by 'tiger';</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> grant all on roller.* to scott@'localhost' identified by 'tiger';</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> use roller;</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> source createdb.sql</FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"> mysql> quit</FONT></FONT></PRE><P CLASS="western">
-<B>NOTES</B></P>
+<P CLASS="western"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><I>If
+you're using Tomcat, check the Tomcat Considerations section below,
+otherwise you are ready to move on to Section 4: Download and
+un-package Roller.</I></FONT></FONT></P>
+<H2 CLASS="western">3.1Tomcat: JavaMail and Activation</H2>
+<P CLASS="western" STYLE="font-style: normal"><FONT SIZE=3><FONT FACE="Times New Roman, serif">Tomcat
+does not include the Java Mail and Activation jars that Roller needs
+for email notification, So, if you like to use Roller's e-mail
+notification features, you'll need to download those jars and place
+them in Tomcat's classpath. Download them from Sun
+(</FONT></FONT><A HREF="http://java.sun.com/products/javamail"><FONT SIZE=3><FONT FACE="Times New Roman, serif">http://java.sun.com/products/javamail</FONT></FONT></A><FONT SIZE=3><FONT FACE="Times New Roman, serif">)
+and place them in Tomcat's <FONT FACE="Courier New, monospace">common/lib</FONT>
+directory.</FONT></FONT></P>
+<H2 CLASS="western">3.2Tomcat: URI encoding needed for I118N</H2>
+<P CLASS="western"><SPAN STYLE="font-style: normal"><FONT SIZE=3><FONT FACE="Times New Roman, serif">Roller
+supports internationalization (I18N), but on Tomcat some additional
+configuration is necessary. You must ensure that Tomcat's URI
+encoding is set to UTF-8. You can do this by editing the Tomcat
+configuration file </FONT><FONT FACE="Courier New">conf/server.xml</FONT><FONT FACE="Times New Roman, serif">
+and adding </FONT><FONT FACE="Courier New, monospace">URIEncoding=âUTF-8â</FONT><FONT FACE="Times New Roman, serif">
+to each connector element, as shown below:</FONT></FONT></SPAN></P>
+<PRE> <Connector port="8080"
+ maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
+ enableLookups="false" redirectPort="8443" debug="0"
+ acceptCount="100" connectionTimeout="20000"
+ disableUploadTimeout="true"
+ <B>URIEncoding="UTF-8" </B>/></PRE><P CLASS="western" STYLE="margin-bottom: 0in">
+<BR>
+</P>
+<P CLASS="western" STYLE="font-style: normal"><FONT FACE="Times New Roman, serif"><FONT SIZE=3>And
+make sure you do this for <I>every</I> connector through which you
+use Roller. For example, if you use the AJP connector or HTTPS
+connector you need to add the <TT>URIEncoding="UTF-8"</TT>
+attribute to those connectors as well.</FONT></FONT></P>
+<H1 CLASS="western">4Download and un-package Roller</H1>
+<P CLASS="western">Download the Apache Roller release file from
+<A HREF="http://roller.apache.org/">http://roller.apache.org</A>. If
+you're a Windows user download the .zip file and use your favorite
+ZIP program to unzip the release into a directory on your computer's
+disk. Unix users can download the .tar.gz file and use GNU tar to
+un-package.
+</P>
+<H2 CLASS="western">4.1Installation directory layout</H2>
+<P CLASS="western">Once you've unpackaged the files you'll find a
+directory structure like this:</P>
+<P CLASS="western"><IMG SRC="roller-install-guide_html_m74822c69.png" NAME="graphics2" ALIGN=LEFT WIDTH=257 HEIGHT=379 BORDER=0><BR CLEAR=LEFT><BR><BR>
+</P>
+<P CLASS="western">The <FONT FACE="Courier New, monospace">LICENCE.txt</FONT>
+and <FONT FACE="Courier New, monospace">NOTICE.txt</FONT> files
+contain the Apache Software License and other legal notices related
+to the release. The <FONT FACE="Courier New, monospace">README.txt</FONT>
+file just points to the documentation in the <FONT FACE="Courier New, monospace">docs</FONT>
+directory.</P>
+<H2 CLASS="western">4.2The Roller Weblogger WAR
+</H2>
+<P CLASS="western">The Roller Weblogger application itself is in the
+directory <FONT FACE="Courier New, monospace">webapp/roller</FONT>
+and is organized using the standard Java EE WAR directory structure.
+Generally speaking, you won't need to modify any files in side the
+director. You can deploy it as is, in directory form, or you can
+package it up as a .war if you prefer to deploy as a file.</P>
+<P CLASS="western">For example, here's how you'd package it up as a
+WAR:</P>
+<PRE> % cd apache-roller-X.0/webapp/roller
+ % jar cvf ../roller.war *</PRE><P CLASS="western" STYLE="font-style: normal">
+<BR><BR>
+</P>
+<H1 CLASS="western">5Prepare your database for Roller</H1>
+<P CLASS="western">Before you can install Roller you'll probably need
+to some work to prepare your database for Roller.
+</P>
+<P CLASS="western">You need some place to put the Roller tables. Some
+folks call this a table-space, but we refer to it as a <I>database</I>.
+You need to create a database for Roller, or get your database
+administrator to do it for you. And second, you need to have a JDBC
+driver installed for you database of choice.</P>
+<P CLASS="western"><I>If you're installing on Glasfish and using it's
+built-in JavaDB/Derby database, you can skip this section; there's no
+need to create a database in Derby and Glassfish already includes the
+Derby JDBC driver.</I></P>
+<H2 CLASS="western">5.1Create a database for Roller
+</H2>
+<P CLASS="western">If you're luck enough to have your own database
+administrator, ask them to setup a database for Roller. When they are
+done, ask them to provide you with this information, you'll need it
+later:</P>
<UL>
- <LI><P CLASS="western">For MySQL, don't forget to call <I>flush
- privileges </I><SPAN STYLE="font-style: normal">to commit your
- changes to MySQL.</SPAN></P>
- <LI><P CLASS="western">To check whether your MySQL is setup
- properly, use the command line mysql program to connect using the
- user name and password you created. For example (we use 127.0.0.1
- here instead of localhost to ensure that TCP/IP networking is
- enabled):</P>
+ <LI><P CLASS="western">Username and password for connecting to
+ database</P>
+ <LI><P CLASS="western">JDBC connection URL for database</P>
+ <LI><P CLASS="western">JDBC driver class name</P>
</UL>
-<P CLASS="western" STYLE="margin-bottom: 0in"> <FONT FACE="Courier New">mysql
-roller -h 127.0.0.1 -u scott -ptiger</FONT></P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP5DeployRollerToYourApplicationServer5"></A><A NAME="ref-InstallationGuide_2.x-5"></A>
-STEP 5: Deploy Roller to your application server</H2>
-<P CLASS="western">To deploy Roller you will need to inform your
-application server:</P>
+<P CLASS="western">If you don't have a database administrator then
+you'll have to refer to the documentation for your database and do it
+yourself. You need to create a database for Roller, protected by
+username and password. For example, if you're using MySQL you might
+do something like this:</P>
+<PRE> <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">% mysql -u root -p</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">password: *****</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">mysql> create database rollerdb;</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">mysql> grant all on rollerdb.* to scott@'%' identified by 'tiger';</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">mysql> grant all on rollerdb.* to scott@localhost identified by 'tiger';</FONT></FONT></PRE><H2 CLASS="western">
+5.2Check your JDBC driver setup</H2>
+<P CLASS="western">Make sure that you have the correct JDBC driver
+installed in your server. Usually, this is as simple as downloading
+the JDBC driver jar(s) and placing it (or them) into your server's
+classpath. For example, on Tomcat you place them in <FONT FACE="Courier New, monospace">common/lib</FONT>.</P>
+<H2 CLASS="western">5.3MySQL and Oracle considerations</H2>
+<P CLASS="western">Based on our experience supporting MySQL, we have
+the following recommendations:</P>
<UL>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">Where to find the
- Roller installation directory</P>
- <LI><P CLASS="western" STYLE="margin-bottom: 0in">How to configure
- the Roller database data-source under the JNDI name <FONT FACE="Courier New">jdbc/rollerdb
- </FONT>
+ <LI><P CLASS="western">For MySQL, make sure that TCP/IP networking
+ is enabled.
</P>
- <LI><P CLASS="western">How to configure the Roller email session
- under the JNDI name <FONT FACE="Courier New, monospace">mail/Session</FONT></P>
+ <LI><P CLASS="western">For MySQL 4.1.x use the J/Connector 3.0.X
+ JDBC drivers instead of the newer 3.1.X series.</P>
+ <LI><P CLASS="western">For MySQL 5.X use the J/Connector 3.1.X JDBC
+ drivers instead of the newer 3.1.X series.</P>
+ <LI><P CLASS="western">Make sure you enable MySQL's UTF-8 support.
+ See this page for
+ details:<BR><A HREF="http://rollerweblogger.org/wiki/Wiki.jsp?page=SetupUTF8onMySQL">http://rollerweblogger.org/wiki/Wiki.jsp?page=SetupUTF8onMySQL</A>
+ </P>
+ <LI><P CLASS="western">For Oracle users, use the 10g (10.1.0.2
+ higher) drivers which should be packaged as ojdbc14.jar, even if
+ operating on Oracle 9 server.</P>
</UL>
-<P CLASS="western" STYLE="margin-bottom: 0in">For Tomcat you can do
-this by creating what's known as a context configuration file named
-<FONT FACE="Courier New">roller.xml</FONT> and placing that file in
-the Tomcat <FONT FACE="Courier New">conf/Catalina/localhost</FONT>
-directory.
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><B>Example context
-configuration file for Tomcat 5.0.X users</B></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in; font-weight: medium">The
-portions shown in bold are the ones that you'll probably have to
-change. Make sure you set the docBase to point to your Roller
-installation directory. Make sure you set the JDBC connection string
-to point to your database and the database username and password too.</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<PRE><FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><Context path="/roller" </FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">docBase="<B>/usr/local/apache-roller-3.2/webapp/roller</B>" debug="0"></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><Resource name="jdbc/rollerdb" auth="Container" type="javax.sql.DataSource" /></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><ResourceParams name="jdbc/rollerdb"></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><name>factory</name></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><value>org.apache.commons.dbcp.BasicDataSourceFactory</value></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><name>driverClassName</name></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><value>com.mysql.jdbc.Driver</value></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter> </FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><name>url</name></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><value></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><B>jdbc:mysql://localhost:3306/roller?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;mysqlEncoding=utf8</B></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></value></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter><name>username</name><value><B>scott</B></value></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter><name>password</name><value><B>tiger</B></value></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter><name>maxActive</name><value>20</value></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter><name>maxIdle</name><value>3</value></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter><name>removeAbandoned</name><value>true</value></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter><name>maxWait</name><value>3000</value></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></ResourceParams></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><!-- If you want e-mail features, un-comment the section below --></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><!--</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><Resource name="mail/Session" auth="Container" type="javax.mail.Session"/></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><ResourceParams name="mail/Session"></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><name>mail.smtp.host</name></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"><value>mailhost.example.com</value></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></parameter></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></ResourceParams></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt">--></FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=2 STYLE="font-size: 11pt"></Context></FONT></FONT></PRE><P CLASS="western" STYLE="margin-bottom: 0in; page-break-before: always">
-<B>Example context configuration file for Tomcat 5.5.X users</B></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in; font-weight: medium">The
-portions shown in bold are the ones that you'll probably have to
-change. Make sure you set the docBase to point to your Roller
-installation directory. Make sure you set the JDBC connection string
-to point to your database and the database username and password too.</P>
-<P CLASS="western" STYLE="margin-bottom: 0in; font-weight: medium"><BR>
-</P>
-<PRE><FONT FACE="Courier New"><FONT SIZE=3><Context path="/roller" </FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>docBase="<B><FONT SIZE=2 STYLE="font-size: 11pt">/usr/local/apache-roller-3.2/webapp/roller</FONT></B>" debug="0"></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3><Resource name="jdbc/rollerdb" auth="Container" </FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>type="javax.sql.DataSource"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>driverClassName="com.mysql.jdbc.Driver"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>url="<B>jdbc:mysql://localhost:3306/roller?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;mysqlEncoding=utf8</B>"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>username="<B>scott</B>"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>password="<B>tiger</B>"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>maxActive="20"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>maxIdle="3"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>removeAbandoned="true"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>maxWait="3000" /></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3><!-- If you want e-mail features, un-comment the section below --></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3><!--</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3><Resource name="mail/Session" auth="Container" </FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>type="javax.mail.Session"</FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>mail.smtp.host="mailhost.example.com" /></FONT></FONT>
- <FONT FACE="Courier New"><FONT SIZE=3>--></FONT></FONT>
-<FONT FACE="Courier New"><FONT SIZE=3></Context></FONT></FONT></PRE><P CLASS="western">
+<H1 CLASS="western">6Configure Roller</H1>
+<P CLASS="western">It is possible for you to configure Roller by
+creating and editing only one file:</P>
+<P CLASS="western"> <FONT FACE="Courier New, monospace">roller-custom.properties</FONT></P>
+<P CLASS="western">That file is a simple Java properties file, a text
+file that overrides settings defined in Roller's internal
+<FONT FACE="Courier New, monospace">roller.properties </FONT>file. To
+configure Roller you look at Roller's internal properties file,
+decide which properties you need to override and then set those in
+your <FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+file.</P>
+<P CLASS="western">You can find the full text of Roller's internal
+<FONT FACE="Courier New, monospace">roller.properties</FONT> file in
+<B>Section 11</B> and we encourage you to read it over, but we'll get
+you started right here and now with a simple example that shows you
+the bare minimum database configuration settings that you need to run
+Roller.</P>
+<P CLASS="western">Create a text file named <FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+with the content below, but replacing the bold/italic text the
+settings appropriate for your database and mail server.</P>
+<PRE> installation.type=auto
+ database.configurationType=jdbc
+ database.jdbc.driverClass=<B><I>JDBC driver class name</I></B>]
+ database.jdbc.connectionURL=<B><I>JDBC connection URL</I></B>
+ database.jdbc.username=<B><I>database username</I></B>
+ database.jdbc.password=<B><I>database password</I></B>
+ mail.configurationType=properties
+ mail.hostName=<B><I>mail server hostname</I></B></PRE><P CLASS="western">
<BR><BR>
</P>
-<P CLASS="western"><B>NOTES</B></P>
-<UL>
- <LI><P CLASS="western"><B>Email configuration</B>. If you want to
- use email notification of comments, group blogging invitations and
- other events, you'll have to enable that in your application
- server. For Tomcat, you can do that by uncommenting the indicated
- sections of the context configuration file above. No matter what
- application server you use, you'll also have to uncomment the
- <FONT FACE="Courier New, monospace">mail/Session</FONT> resource
- reference <FONT FACE="Courier New, monospace"><resource-ref></FONT>
- near the end of the roller/WEB-INF/web.xml file.</P>
- <LI><P CLASS="western"><B>The max_user_connections error</B>. If
- Roller starts up fine but later fails and you find an error like the
- one below in your roller.log file then try dropping your <FONT FACE="Courier New">maxActive</FONT>,
- <FONT FACE="Courier New">maxIdle</FONT>, and <FONT FACE="Courier New">removeAbandoned</FONT>
- values. Depending on your database configuration you may have to go
- pretty low, such as setting <FONT FACE="Courier New">maxActive</FONT>
- to 6, <FONT FACE="Courier New">maxIdle</FONT> to 3 and
- <FONT FACE="Courier New">removeAbandonedTimeout</FONT> to 60.
- </P>
-</UL>
+<P CLASS="western">The <FONT FACE="Courier New, monospace">installation.type=auto</FONT>
+property tells Roller to operate in automatic installation mode. In
+this mode Roller will provide very detailed error output to help you
+debug database connection problems. If Roller finds that the database
+exists but its tables are not, it will offer to run the database
+creation scripts. If find finds that the tables are there, but they
+are not up-to-date Roller will offer to upgrade them for you. Once
+your Roller installation is complete and you are ready to go âliveâ
+then you should set<FONT FACE="Courier New, monospace">
+installation.type=manual</FONT>.</P>
+<H2 CLASS="western">6.1MySQL example</H2>
+<P CLASS="western">Here is an example roller-custom.properties file
+that shows how to setup a MySQL connection. It shows the MySQL JDBC
+driver class name, an example MySQL connection URL and
+username/password settings for the mail connection.</P>
+<PRE> installation.type=auto
+ database.configurationType=jdbc
+ database.jdbc.driverClass=<B><I>com.mysql.jdbc.Driver</I></B>
+ database.jdbc.connectionURL=<B><I>jdbc:mysql://localhost:3306/rollerdb</I></B>
+ database.jdbc.username=<B><I>scott</I></B>
+ database.jdbc.password=<B><I>tiger</I></B>
+ mail.configurationType=properties
+ mail.hostName=<TT><B><I><FONT FACE="Courier New">smtp-server.example.com</FONT></I></B></TT>
+<TT> <FONT FACE="Courier New"><SPAN STYLE="font-weight: medium"><SPAN STYLE="font-style: normal">mail.username=</SPAN></SPAN><B><I>scott</I></B></FONT></TT>
+<TT> <FONT FACE="Courier New"><SPAN STYLE="font-weight: medium"><SPAN STYLE="font-style: normal">mail.password=</SPAN></SPAN><B><I>tiger</I></B></FONT></TT>
+</PRE><P CLASS="western">
+Next, we'll deploy Roller.</P>
+<H1 CLASS="western" STYLE="page-break-before: always">7Deploy Roller</H1>
+<P CLASS="western">Now that you've got the Roller WAR and you've
+created your <FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+file, you're ready to deploy Roller to your server. First, deploy
+your properties file.</P>
+<H2 CLASS="western">7.1Put <FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+in classpath</H2>
+<P CLASS="western">Roller can look for your properties file in a
+number of ways and you can see <B>Section 11</B> for details. The
+simplest thing for you to do is to place the file in your application
+server's classpath, by dropping it into a <FONT FACE="Courier New, monospace">classes</FONT>
+directory. On startup, Roller will find it there. Here's how to do it
+on some popular servers:</P>
<UL>
- <LI><P CLASS="western" STYLE="font-style: normal"><FONT FACE="Courier New"><FONT SIZE=2> User
- scott@localhost has more than 'max_user_connections' active
- connections</FONT></FONT></P>
+ <LI><P CLASS="western">On Tomcat you can simply copy the file into
+ Tomcat's <FONT FACE="Courier New, monospace">common/classes</FONT>
+ directory.</P>
+ <LI><P CLASS="western">On Glassfish, copy can copy it to your
+ domain's <FONT FACE="Courier New, monospace">lib/classes</FONT>
+ directory.</P>
</UL>
-<P CLASS="western"><BR><BR>
-</P>
-<P CLASS="western"><BR><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western">Now you're ready to deploy Roller itself.</P>
+<H2 CLASS="western">7.2Deploy Roller via administration console</H2>
+<P CLASS="western">Use your server's administration console to deploy
+the Roller web application. You can deploy as a directory, in which
+case you'll have to enter the path to your Roller installation's
+<FONT FACE="Courier New, monospace">webapp/roller</FONT> directory.
+Or you can deploy as a WAR file, in which case you will have to have
+created a WAR file as we described in <B>Section 4.2</B>.
+</P>
+<P CLASS="western">For example, here's the Web Application deployment
+page in the Tomcat Admin Console:</P>
+<P CLASS="western"><SPAN STYLE="background: #ffff00">TODO Screenshot
+of Tomcat Admin Console</SPAN></P>
+<P CLASS="western">And, another example is Web Application deployment
+page in the Glassfish Admin Console:</P>
+<P CLASS="western"><SPAN STYLE="background: #ffff00">TODO Screenshot
+of Glassfish Admin Console</SPAN></P>
+<H1 CLASS="western">8Getting started with Roller</H1>
+<P CLASS="western">You're not quite done with the installation
+process Now you're ready to start using Roller, so we'll walk you
+through getting started, registering a user and setting up a blog.
+We'll also discuss briefly what happens when there is an error.
</P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP6ConfigureYourApplicationServerForUTF86"></A>
-STEP 6: Check your internationalization settings</H2>
-<P CLASS="western" STYLE="margin-bottom: 0in">Roller's approach to
-internationalization (I18N) is to do everything in UTF-8. So, if you
-want I18N to work properly, you'll need to configure your application
-server and your web server to use UTF-8 encoding.
-</P>
-<H4 CLASS="western">Check your application server's URI encoding
-setting!</H4>
-<P CLASS="western" STYLE="margin-bottom: 0in">Make sure that your web
-application server uses UTF-8 to encode URI's. This allows you to use
-diacritical characters like 'ç' in your URLs. This is
-important for Roller because weblog entry titles are used in URLs.
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">For example, in Tomcat
-the URI encoding is specified in the connectors that are configured
-in the Tomcat configuration file <FONT FACE="Courier New">conf/server.xml</FONT>.
-Here's a connector with the URI encoding attribute set properly:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"> <FONT FACE="Courier New"><Connector
-port="8080"</FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">maxThreads="150" </FONT>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">minSpareThreads="25"
-maxSpareThreads="75"</FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">enableLookups="false" </FONT>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">redirectPort="8443" </FONT>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">acceptCount="100"</FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"> <FONT FACE="Courier New">debug="0"
-</FONT>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">connectionTimeout="20000"</FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New">disableUploadTimeout="true" </FONT>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New"><B>URIEncoding="UTF-8" </B> /></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><SPAN STYLE="font-weight: medium">And
-make sure you do this for <I>every</I> connector through which you
-use Roller. For example, if you use the AJP connector or HTTPS
-connector you need to add the </SPAN><TT><SPAN STYLE="font-weight: medium">URIEncoding="UTF-8"</SPAN></TT><SPAN STYLE="font-weight: medium">
-attribute to those connectors as well.</SPAN></P>
-<P CLASS="western"><BR><BR>
-</P>
-<P CLASS="western"><BR><BR>
+<H2 CLASS="western">8.1Navigate to Roller and finish the install
+</H2>
+<P CLASS="western">Navigate to Roller, if you are using a default
+Tomcat or Glassfish installation then then URL of Roller is probably
+<A HREF="http://localhost:8080/roller">http://localhost:8080/roller</A>.
+You will see either a web page of error messages, a web page offering
+to create database tables for you or web page asking you to complete
+the installation by registering an admin user and creating a
+front-page blog. First, let's talk about what happens when things go
+wrong.</P>
+<H3 CLASS="heading-4-western">Problems?</H3>
+<P CLASS="western">If there's a problem with your database
+configuration, Roller will display a page or error messages to help
+you diagnose the problem. It's possible that you entered the wrong
+JDBC driver class name, connection URL, username or password. Or
+perhaps your database is not running. Use the information provided to
+determine what is wrong, fix it and then redeploy Roller.</P>
+<P CLASS="western"><SPAN STYLE="background: #ffff00">TODO Screenshot
+of error page</SPAN></P>
+<H3 CLASS="heading-4-western">Automatic tables creation</H3>
+<P CLASS="western">If your database configuration is good but Roller
+cannot find its database tables, then Roller will offer to create
+those pages automatically for you. If you give the go-ahead, Roller
+will run the appropriate database creation script for your database
+and then show you the results. You can then proceed to the next step
+to setup your first user account and weblog.</P>
+<H2 CLASS="western">8.2Register a user and create a weblog</H2>
+<P CLASS="western">If Roller starts up fine but doesn't find a
+front-page weblog then it will display the Completing Your
+Installation below that explains how to register your first user,
+create your first weblog and setup your site's front page.</P>
+<P CLASS="western"><SPAN STYLE="background: #ffff00">TODO Screenshot
+of register/create page</SPAN></P>
+<P CLASS="western">You have to decide what you want as the front-page
+of your Roller site. If you are using Roller to run your personal
+weblog, then you probably want your weblog to be the front-page of
+the site. In this case, create a weblog for yourself, <I>don't</I>
+choose the front-page theme but <I>do</I> set your weblog as the
+front-page weblog for the site.
+</P>
+<P CLASS="western">If you are using Roller to run a community of
+multiple weblogs, then you'll probably want to display an aggregated
+front-page combining all weblogs on the site. In that case, create a
+weblog to serve as the front-page, set it as the front-page weblog
+and make sure you set the âaggregated front-pageâ setting on the
+Server Admin page.
+</P>
+<H3 CLASS="heading-4-western">Don't forget: Reset the
+<FONT FACE="Courier New, monospace">installation.type</FONT> flag</H3>
+<P CLASS="western">Now that you're done with the installation you
+should turn off Roller's auto-installation system. Edit your
+<FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+file and set:</P>
+<PRE> installation.type=manual
+</PRE><P CLASS="western">
+Then restart your server or Roller so that it accepts the new
+setting.</P>
+<H3 CLASS="heading-4-western">What's next?</H3>
+<P CLASS="western">Once you've gotten Roller up and running refer to
+the Roller User Guide for more information on running your Roller
+system and your weblog. For information on customizing your weblog,
+refer to the Roller Template Guide. If you can't find what you want
+in the documentation then subscribe to the Roller user mailing list
+and ask your questions there.</P>
+<P CLASS="western"> Roller user and developer mailing lists:<BR>
+<A HREF="http://cwiki.apache.org/confluence/display/ROLLER/Roller+Mailing+Lists">http://cwiki.apache.org/confluence/display/ROLLER/Roller+Mailing+Lists</A>
+</P>
+<H1 CLASS="western">9Configuration tips and tricks</H1>
+<P CLASS="western">This section covers some tips and tricks that can
+help you get the most out of Roller. It covers Roller's Planet feed
+aggregator, Acegi setup and how to setup Roller to use
+server-provided resources.</P>
+<H2 CLASS="western">9.1Setting up Roller's Planet feed aggregator</H2>
+<P CLASS="western">Roller includes a RSS/Atom feed aggregator that
+makes it possible to run a site like <A HREF="http://blogs.sun.com/">http://blogs.sun.com</A>
+which provides weblogs for thousands of writers and an aggregated
+front-page that displays the most recent posts form those plus dozens
+of Sun bloggers from other sites such as blogger.com, typepad.com and
+other services. Here's what you need to do.</P>
+<H3 CLASS="heading-4-western">STEP 1: Create a Planet cache directory</H3>
+<P CLASS="western">Roller Planet needs a cache directory in which to
+store the feeds it fetches. By default, Roller Planet will put it's
+cache in your home directory under <FONT FACE="Courier New, monospace">roller_data/planetcache</FONT>.
+If you want to place the cache somewhere else, you must override the
+planet.aggregator.cache.dir property in your <FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+file. For example:</P>
+<PRE> <FONT SIZE=3><FONT FACE="Courier New, monospace">planet.aggregator.cache.dir=c:\\roller_data\planetcache</FONT></FONT>
+</PRE><P CLASS="western">
+Whether you override that property or not, <B>you must create the
+cache directory</B>. Planet will not work unless the cache directory
+exists and is writable by Roller.</P>
+<H3 CLASS="heading-4-western">STEP 2: Enable Planet Roller properties</H3>
+<P CLASS="western">Enable Planet by adding the following to your
+<FONT FACE="Courier New, monospace">roller-custom.properties</FONT>
+file:</P>
+<PRE> <FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New, monospace">planet.aggregator.enabled=<B>true</B></FONT></FONT>
+
+ <FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New, monospace"># Tasks which are enabled. Only tasks listed here will be run.<BR> tasks.enabled=ScheduledEntriesTask,ResetHitCountsTask,\<BR> TurnoverReferersTask,PingQueueTask,<B>RefreshPlanetTask,SyncWebsitesTask</B></FONT></FONT>
+
+ <FONT SIZE=2 STYLE="font-size: 11pt"># Set of page models specifically for site-wide rendering</FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">rendering.siteModels=\</FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt">org.apache.roller.weblogger.ui.rendering.model.SiteModel,\</FONT>
+ <FONT SIZE=2 STYLE="font-size: 11pt"><B>org.apache.roller.weblogger.ui.rendering.model.PlanetModel</B></FONT></PRE><P CLASS="western">
+<BR><BR>
</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
+<P CLASS="western"><FONT SIZE=3>Those property settings enable Planet
+and enable the Planet tasks, both the <I>RefreshPlanetTask</I>, which
+runs every hour and fetches all RSS/Atom feed subsciptions, and the
+<I>SyncWebsitesTask</I>, which runs every midnight and ensures that
+each weblog in the Roller system is represented by a subscription in
+the Planet aggregator. To enable usage of the PlanetModel in the
+front-page weblog, we also override the <FONT FACE="Courier New, monospace">rendering.siteModels</FONT>
+property.</FONT></P>
+<P CLASS="western"><FONT SIZE=3>Once you've made those property
+settings restart Roller and proceed to the next step.</FONT></P>
+<H3 CLASS="heading-4-western">Display your Planet aggregations</H3>
+<P CLASS="western">You can use Roller's UI to add external RSS/Atom
+feeds to the Planet setup. To display these feeds you'll need to do a
+little template customization. The easier way to get started is to
+Roller's existing Front-Page theme. Here's how.</P>
+<P CLASS="western">Create a weblog to server as the front-page of
+your Roller site. Start with the Front-Page theme and customize it.
+Edit the weblog template and look for the part that mentions
+PLANET-entries. Comment-out the SITE-WIDE part and un-comment the
+PLANET-entries part. The double hash â##â marks indicate a
+commented-out line. The code should look like this:<BR><BR><BR>
</P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP7SetupRollerDataDirectories7"></A><A NAME="ref-InstallationGuide_2.x-7"></A>
-STEP 7: Setup Roller data directories
-</H2>
-<P CLASS="western">Roller stores file uploads, search index files,
-cache files and log files on disk. So before you start, check to make
-sure the directories that Roller expects exist and are writable by
-the Tomcat process.
-</P>
-<H3 CLASS="western">STEP 7.1: Create <TT>uploads</TT> directory</H3>
-<P CLASS="western" STYLE="margin-bottom: 0in">By default, Roller
-saves uploaded files under the directory:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><TT><FONT FACE="Courier New"> ${user.home}/roller_data/uploads</FONT></TT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">Where <TT><FONT FACE="Courier New">${user.home}</FONT></TT>is
-the Java system property that normally evaluates to the home
-directory of the user identity executing the server's JVM process.
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">In most cases, this
-default will probably work fine for you. However, for security
-reasons some application servers are set up to run as a server user
-identity whose home directory does not exist or is not writable by
-the server user itself. If this is the case for your server, override
-the property <TT><FONT FACE="Courier New">uploads.dir</FONT></TT> in
-the <FONT FACE="Courier New">roller.properties</FONT> file. See step
-8 for more information on the <FONT FACE="Courier New">roller.properties</FONT>
-file.</P>
-<H3 CLASS="western">STEP 7.2: Create <TT>search-index</TT> directory</H3>
-<P CLASS="western">By default, Roller creates and maintains its text
-search index data in files under the directory</P>
-<P CLASS="western"><TT><FONT FACE="Courier New"> ${user.home}/roller_data/search-index</FONT></TT>
-</P>
-<P CLASS="western">Again, <TT><FONT FACE="Courier New">${user.home}</FONT>
-</TT>is the Java system property that normally evaluates to the home
-directory of the user identity executing the server's JVM process.
-You can specify a different directory by overriding the property
-<TT><FONT FACE="Courier New">search.index.dir</FONT> </TT>in
-<FONT FACE="Courier New">roller.properties</FONT><FONT FACE="Thorndale">.</FONT>
-See step 8 for more information on the Roller configuration override
-file.</P>
-<H3 CLASS="western">STEP 7.3: Create <TT>planet-cache</TT> directory
-(optional)</H3>
-<P CLASS="western">You only need to do this if you are planning on
-using Roller's integrated planet aggregator: create a directory for
-the planet cache (e.g. <FONT FACE="Courier New">/var/roller/planet-cache</FONT>).
-<SPAN STYLE="font-weight: medium"><FONT SIZE=2><FONT FACE="Courier New">
-</FONT></FONT></SPAN>See the Roller User Guide for more information
-on configuring Roller's built-in aggregator.</P>
-<H3 CLASS="western">STEP 7.4: Make sure that the <TT>logs</TT>
-subdirectory exists</H3>
-<P CLASS="western" STYLE="margin-bottom: 0in">The <TT><FONT FACE="Courier New">roller.log</FONT>
-</TT>file is written to the location:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><TT><FONT FACE="Courier New"> ${catalina.base}/logs/roller.log</FONT></TT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">Make sure that that
-this directory exists. Tomcat 5.0.X users will normally have this
-directory by default. Tomcat 5.5.x users may need to create this
-subdirectory under their base directory.
-</P>
-<H2 CLASS="western" STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP8ReviewRollerConfiguration8"></A>
-STEP 8: Review Roller configuration</H2>
-<P CLASS="western">Before you start Roller for the first time, review
-your configuration.</P>
-<H3 CLASS="western">STEP 8.1: Review the
-<FONT FACE="Courier New">WEB-INF/classes/roller.properties</FONT>
-file</H3>
-<P CLASS="western">Roller tries to pick a good set of configuration
-defaults which should let anyone start up the application without
-much work, but here are a few properties which are custom to each
-install and should be set before you start up Roller. We'll first
-talk about what ways there are for defining your custom Roller
-configuration, then show which properties we think you should set.
-<B>NOTE</B>: the default <FONT FACE="Courier New">roller.properties</FONT>
-file is shown in Appendix B.</P>
-<H4 CLASS="western"><A NAME="section-ConfigurationGuide_2.x-WhereToDefineCustomProperties"></A>
-Where to define custom properties</H4>
-<P CLASS="western" STYLE="margin-bottom: 0in">There are three ways
-you can alter the default configuration for Roller.
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><B>1)</B> Define a
-<FONT FACE="Courier New">roller-custom.properties</FONT> file and
-place it somewhere at the root of one of your classpath locations.
-This is the recommended way to override Roller configuration
-properties. For example:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> $TOMCAT_HOME/common/classes/roller-custom.properties</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><B>2) </B>Specify a
-custom properties file via JVM option. This is another good option
-but is more dependant on what servlet container you use. For example:</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> #
-this is how you might do it for tomcat</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> JAVA_OPTS="-Droller.custom.config=/path/to/properties/file"</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> export
-$JAVA_OPTS</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> $TOMCAT_HOME/bin/startup.sh</FONT></FONT></P>
-<H4 CLASS="western"><A NAME="section-ConfigurationGuide_2.x-WhatPropertiesYouShouldSet"></A>
-<B>What properties you should set</B></H4>
-<P CLASS="western" STYLE="margin-bottom: 0in">We are going to assume
-you have defined a <FONT FACE="Courier New">roller-custom.properties</FONT>
-file and placed it in your classpath somewhere. To override any of
-the default Roller properties you simply add a line with the proper
-key and the new value you wish to use.
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">Here is a sample
-<FONT FACE="Courier New">roller-custom.properties</FONT> with the few
-properties that should be overridden.</P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> uploads.dir=/app/roller/roller_data/uploads</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> search.index.dir=/app/roller/roller_data/search-index</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in">
-<FONT FACE="Courier New"><FONT SIZE=3>passwds.encryption.enabled=true</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Courier New"><FONT SIZE=3> #
-etc, etc, etc ... any other properties you want to override</FONT></FONT></P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><BR>
-</P>
-<P CLASS="western" STYLE="margin-bottom: 0in"><FONT FACE="Times New Roman, serif"><FONT SIZE=3><B>NOTE:
[... 2246 lines stripped ...]