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 2006/03/23 17:51:05 UTC
svn commit: r388209 - in /incubator/roller/trunk/docs: installguide/
installguide/generated/ userguide/ userguide/generated/
userguide/generated/html/
Author: snoopdave
Date: Thu Mar 23 08:51:02 2006
New Revision: 388209
URL: http://svn.apache.org/viewcvs?rev=388209&view=rev
Log:
Updating docs for 2.2 RC
Added:
incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide_html_9cad71a.png (with props)
incubator/roller/trunk/docs/userguide/generated/roller-user-guide.pdf (with props)
Modified:
incubator/roller/trunk/docs/installguide/generated/roller-install-guide.html
incubator/roller/trunk/docs/installguide/generated/roller-install-guide.pdf
incubator/roller/trunk/docs/installguide/generated/roller-install-guide.txt
incubator/roller/trunk/docs/installguide/roller-install-guide.odt
incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide.html
incubator/roller/trunk/docs/userguide/roller-user-guide.odt
Modified: incubator/roller/trunk/docs/installguide/generated/roller-install-guide.html
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/installguide/generated/roller-install-guide.html?rev=388209&r1=388208&r2=388209&view=diff
==============================================================================
--- incubator/roller/trunk/docs/installguide/generated/roller-install-guide.html (original)
+++ incubator/roller/trunk/docs/installguide/generated/roller-install-guide.html Thu Mar 23 08:51:02 2006
@@ -7,7 +7,7 @@
<META NAME="AUTHOR" CONTENT="Dave Johnson">
<META NAME="CREATED" CONTENT="20060123;11164600">
<META NAME="CHANGEDBY" CONTENT="Dave Johnson">
- <META NAME="CHANGED" CONTENT="20060201;11261500">
+ <META NAME="CHANGED" CONTENT="20060323;11154300">
<STYLE>
<!--
@page { size: 8.5in 11in; margin: 0.79in }
@@ -27,7 +27,7 @@
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=7 STYLE="font-size: 32pt"><B>Apache
Roller</B></FONT></P>
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><A NAME="DDE_LINK1"></A><FONT SIZE=5 STYLE="font-size: 20pt"><B>Version
-2.1-incubating</B></FONT></P>
+2.2-incubating</B></FONT></P>
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
</P>
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
@@ -81,25 +81,25 @@
<FONT FACE="Albany, 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">Introduction 3</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 1: Before you
- install Roller 4</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 2: Unpack the
- Roller distribution 5</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 3: Create
- Roller tables in your database 6</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 4: Install
- required third party jars 7</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Introduction 3</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 4</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 5</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
+ 3: Create Roller tables in your database 6</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
+ 4: Install required third party jars 7</B></FONT></P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 4.1: Install
JDBC driver jar(s) 7</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 4.2: Install
JavaMail and Activation jars 7</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 5: Deploy
- Roller to your application server 8</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 6: Check your
- internationalization settings 10</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 7: Setup
- Roller data directories 11</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 8</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 10</B></FONT></P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
+ 7: Setup Roller data directories 11</B></FONT></P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.1: Create
uploads directory 11</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.2: Create
@@ -108,18 +108,36 @@
planet-cache directory (optional) 11</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 7.4: Make
sure that the logs subdirectory exists 12</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 8: Review
- Roller configuration 13</P>
+ <P STYLE="margin-left: 0.2in; margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>STEP
+ 8: Review Roller configuration 13</B></FONT></P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 8.1: Review
the WEB-INF/classes/roller.properties file 13</P>
<P STYLE="margin-left: 0.59in; margin-bottom: 0in">Where to define
custom properties 13</P>
<P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 8.2: Change
keys in the WEB-INF/security.xml file 14</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">STEP 9: Start
- Tomcat and start using Roller 15</P>
- <P STYLE="margin-left: 0.2in; margin-bottom: 0in">Appendix A: The
- WEB-INF/roller.properties file 16</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 15</B></FONT></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 16</B></FONT></P>
+ <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 1: Shutdown
+ and backup your old Roller [#1] 16</P>
+ <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 2: Install
+ the new Roller [#2] 16</P>
+ <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 3: Copy
+ resources and update configs [#3] 17</P>
+ <P STYLE="margin-left: 0.59in; margin-bottom: 0in">3.1 Copy your old
+ resources and other files you've added 17</P>
+ <P STYLE="margin-left: 0.59in; margin-bottom: 0in">3.2 Remove
+ JavaMail jars if duplicated 17</P>
+ <P STYLE="margin-left: 0.59in; margin-bottom: 0in">3.3 Review
+ configuration properties 17</P>
+ <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 4: Upgrade
+ the database [#4] 17</P>
+ <P STYLE="margin-left: 0.39in; margin-bottom: 0in">STEP 5: Startup
+ your app server [#5] 18</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 19</B></FONT></P>
</DIV>
<P STYLE="margin-bottom: 0in"><BR>
</P>
@@ -139,6 +157,12 @@
<LI><P STYLE="font-weight: medium">Relational Database: MySQL 4.X
(or later)</P>
</UL>
+<P><BR><BR>
+</P>
+<P><B>NOTE: If you're upgrading from an earlier release of Roller,
+read Appendix B first</B></P>
+<P><BR><BR>
+</P>
<P><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
@@ -158,6 +182,8 @@
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><BR><BR>
+</P>
<P STYLE="margin-bottom: 0in"><BR>
</P>
<H2 STYLE="page-break-before: always"><A NAME="section-InstallationGuide_2.x-STEP1Prerequisites1"></A><A NAME="ref-InstallationGuide_2.x-1"></A>
@@ -259,7 +285,7 @@
<FONT FACE="Courier New"><FONT SIZE=2> mysql> source createdb.sql</FONT></FONT>
<FONT FACE="Courier New"><FONT SIZE=2> mysql> quit</FONT></FONT></PRE><P>
<B>Windows example:</B></P>
-<PRE> <FONT FACE="Courier New">C> cd %ROLLER%\dbscripts\mysql</FONT>
+<PRE> <FONT FACE="Courier New">C> cd %ROLLER%\WEB-INF\dbscripts\mysql</FONT>
<FONT FACE="Courier New"> C> mysql -u root -p</FONT>
<FONT FACE="Courier New"> password: *****</FONT>
<FONT FACE="Courier New"> mysql> create database roller;</FONT>
@@ -608,7 +634,7 @@
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 A.</P>
+Appendix B.</P>
<H4><A NAME="section-ConfigurationGuide_2.x-WhereToDefineCustomProperties"></A>
Where to define custom properties</H4>
<P STYLE="margin-bottom: 0in">There are three ways you can alter the
@@ -761,7 +787,166 @@
</P>
<P><BR><BR>
</P>
-<H2 STYLE="page-break-before: always">Appendix A: The
+<H2 STYLE="page-break-before: always">Appendix A: Upgrading an
+existing Roller installation</H2>
+<P>This document describes how to upgrade an existing installation to
+the latest release of Roller by upgrading the Roller database and
+replacing the old Roller files (which are typically found in
+tomcat/webapps/roller) with the new release.
+</P>
+<P>The steps are:</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">STEP 1: Shutdown and backup your
+ old Roller</P>
+ <LI><P STYLE="margin-bottom: 0in">STEP 2: Install the new Roller</P>
+ <LI><P STYLE="margin-bottom: 0in">STEP 3: Copy old configuration</P>
+ <LI><P STYLE="margin-bottom: 0in">STEP 4: Upgrade the database</P>
+ <LI><P STYLE="margin-bottom: 0in">STEP 5: Startup Tomcat
+ </P>
+</UL>
+<H3><A NAME="section-UpgradeGuide_2.1-STEP1ShutdownAndBackupYourOldRoller1"></A><A NAME="ref-UpgradeGuide_2.1-1"></A>
+STEP 1: Shutdown and backup your old Roller [#1]</H3>
+<P>Before you get started with your upgrade, you should shutdown your
+existing Roller install, make a backup of your data, and move the old
+Roller files out of the way. Here is an example of how you'd do this
+with a Tomcat/MySQL setup:
+</P>
+<P STYLE="margin-bottom: 0in">Run shutdown.sh to stop Tomcat, for
+example:
+</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New"><FONT SIZE=3>%
+cd $CATALINA_HOME/bin</FONT></FONT></P>
+<PRE STYLE="margin-bottom: 0.2in"> <FONT FACE="Courier New"><FONT SIZE=3>% ./shutdown.sh</FONT></FONT></PRE><P STYLE="margin-bottom: 0in">
+Backup your database to somewhere safe on your system or to a remote
+file-system, for example if you use MySQL you might do something like
+this:</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New">% mysqldump
+-u scott -p rollerdb > \</FONT></P>
+<P STYLE="margin-bottom: 0in">
+<FONT FACE="Courier New">/somewhere/safe/roller-backup-20050420.dmp</FONT></P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in">Here's an example for PostgreSQL users:
+</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in"> <FONT FACE="Courier New">pg_dump -h
+127.0.0.1 -W -U scott rollerdb > roller.db</FONT></P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<P STYLE="margin-bottom: 0in">Move your Roller files to somewhere
+safe, for example:
+</P>
+<P STYLE="margin-bottom: 0in"><BR>
+</P>
+<PRE> <FONT FACE="Courier New"><FONT SIZE=3>% cd $CATALINA_HOME/webapps</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>% mkdir /somewhere/safe/roller-old</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>% mv roller /somewhere/safe/roller-old</FONT></FONT></PRE><H3>
+<A NAME="section-UpgradeGuide_2.1-STEP2InstallTheNewRoller2"></A><A NAME="ref-UpgradeGuide_2.1-2"></A>
+STEP 2: Install the new Roller [#2]</H3>
+<P>Follow the normal installation instructions to install Roller,
+except:
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in">Don't create a new database for
+ Roller, instead point the new Roller to your old Roller database
+ </P>
+ <LI><P>DO NOT start Tomcat when you are done with the installation,
+ we'll do that later
+ </P>
+</UL>
+<P><BR><BR>
+</P>
+<H3><A NAME="section-UpgradeGuide_2.1-STEP3CopyResourcesAndUpdateConfigs3"></A><A NAME="ref-UpgradeGuide_2.1-3"></A>
+STEP 3: Copy resources and update configs [#3]</H3>
+<H4><A NAME="section-UpgradeGuide_2.1-3.1CopyYourOldResourcesAndOtherFilesYouveAdded"></A>
+3.1 Copy your old resources and other files you've added</H4>
+<P>User uploaded files are, by default, stored in the <TT><FONT FACE="Courier New">/resources</FONT></TT>
+sub-directory of the Roller context directory. You should copy your
+old resources directory into your new Roller installation.
+</P>
+<P>For example, on UNIX you can use <TT><FONT FACE="Courier New">cp
+-r</FONT></TT> to copy the whole directory:
+</P>
+<PRE> <FONT FACE="Courier New"><FONT SIZE=3>% cd %CATALINA_HOME/webapps/roller</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>% cp -r /somewhere/safe/roller-old/roller/resources .</FONT></FONT></PRE><P>
+NOTE: If you have any new themes under roller/themes, make sure to
+copy those as well.
+</P>
+<H4><A NAME="section-UpgradeGuide_2.1-3.2RemoveJavaMailJarsIfDuplicated"></A>
+3.2 Remove JavaMail jars if duplicated</H4>
+<P>In an upgrade installation, you may already have the JavaMail jars
+<TT>mail.jar</TT> and <TT>activation.jar</TT> in your Tomcat
+<TT>common/lib</TT>. If so, you should remove them from the
+<TT>WEB-INF/lib</TT> directory within the web app. (Keep them only in
+the <TT>common/lib</TT> directory.)
+</P>
+<H4><A NAME="section-UpgradeGuide_2.1-3.3ReviewConfigurationProperties"></A>
+3.3 Review configuration properties</H4>
+<P>Review properties as described in STEP #8 of the installation
+guide.</P>
+<H3><A NAME="section-UpgradeGuide_2.1-STEP4UpgradeTheDatabase4"></A><A NAME="ref-UpgradeGuide_2.1-4"></A>
+STEP 4: Upgrade the database [#4]</H3>
+<P>Use the appropriate database upgrade script to upgrade your
+database. To do this, login to your database and run one (or more) of
+the Roller upgrade scripts located in Roller's <FONT FACE="Courier New">WEB-INF/dbscripts</FONT>
+directory that corresponds to your database. There's a directory for
+MySQL, PostgreSQL, HSQLDB and more.
+</P>
+<P>The database script directories
+</P>
+<UL>
+ <LI><P STYLE="margin-bottom: 0in"><FONT FACE="Courier New">WEB-INF/dbscripts/mysql
+ </FONT>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><FONT FACE="Courier New">WEB-INF/dbscripts/postgresql
+ </FONT>
+ </P>
+ <LI><P STYLE="margin-bottom: 0in"><FONT FACE="Courier New">WEB-INF/dbscripts/hsql
+ </FONT>
+ </P>
+ <LI><P>and more...
+ </P>
+</UL>
+<P>There is an upgrade script for each release of Roller. If you're
+upgrading from Roller 2.0, which was the last release before 2.1
+you'll only need to run one script, that's <TT>200-to-210-migration.sql</TT>.
+For example, here's how you'd do it for a MySQL database running on
+UNIX:
+</P>
+<PRE> <FONT FACE="Courier New"><FONT SIZE=3>% cd $CATALINA_HOME/webapps/roller/WEB-INF/dbscripts/mysql</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>% mysql -u root -p</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>password: *****</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>mysql> use roller;</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>mysql> source 200-to-210-migration.sql</FONT></FONT>
+ <FONT FACE="Courier New"><FONT SIZE=3>mysql> quit</FONT></FONT></PRE><P>
+If you're upgrading from an earlier release you'll have to run each
+of the older scripts in order to upgrade your database.</P>
+<H3><A NAME="section-UpgradeGuide_2.1-STEP5StartupTomcat5"></A><A NAME="ref-UpgradeGuide_2.1-5"></A>
+STEP 5: Startup your app server [#5]</H3>
+<P>Use the standard Tomcat <FONT FACE="Courier New">startup.sh</FONT>
+(or <FONT FACE="Courier New">startup.bat </FONT>on Windows) script to
+start Tomcat. As Roller starts up, it will perform some final steps
+to upgrade your database, this may take few seconds longer than your
+average Roller startup.
+</P>
+<P>And you're done!
+</P>
+<P>If Roller doesn't come up, check the logs for exceptions and error
+messages. You should see these messages in the
+<FONT FACE="Courier New">tomcat/logs/catalina.out</FONT> file and in
+<FONT FACE="Courier New">tomcat/logs/roller.log</FONT>. If you still
+can't diagnose and fix your startup program, then subscribe to the
+Roller user mailing list for help. If there are any interesting
+messages in the log files, send those along too.
+</P>
+<P></P>
+<H2></H2>
+<H2 STYLE="page-break-before: always">Appendix B: The
<FONT FACE="Courier New">WEB-INF/roller.properties</FONT> file</H2>
<P>This file defines the default start-up properties for Roller. See
step 8 for instructions on how to override the properties in this
Modified: incubator/roller/trunk/docs/installguide/generated/roller-install-guide.pdf
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/installguide/generated/roller-install-guide.pdf?rev=388209&r1=388208&r2=388209&view=diff
==============================================================================
Binary files - no diff available.
Modified: incubator/roller/trunk/docs/installguide/generated/roller-install-guide.txt
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/installguide/generated/roller-install-guide.txt?rev=388209&r1=388208&r2=388209&view=diff
==============================================================================
--- incubator/roller/trunk/docs/installguide/generated/roller-install-guide.txt (original)
+++ incubator/roller/trunk/docs/installguide/generated/roller-install-guide.txt Thu Mar 23 08:51:02 2006
@@ -1,59 +1,66 @@
-Roller Installation Guide
-Roller Weblogger
-Version 2.1-incubating
+Installation Guide
-Original text is copyright 2002-2004 David M Johnson
-Contributors: Roller team and Sun Microsystems, Inc.
+Apache Roller
+Version 2.2-incubating
+
+Original text is copyright ? 2002-2004 David M Johnson
+Contributors: Roller team and Sun Microsystems, Inc.
Table of Contents
-Introduction
-STEP 1: Before you install Roller
-STEP 2: Unpack the Roller distribution
-STEP 3: Create Roller tables in your database
-STEP 4: Install required third party jars
-STEP 4.1: Install JDBC driver jar(s)
-STEP 4.2: Install JavaMail and Activation jars
-STEP 5: Deploy Roller to your application server
-STEP 6: Check your internationalization settings
-STEP 7: Setup Roller data directories
-STEP 7.1: Create uploads directory
-STEP 7.2: Create search-index directory
-STEP 7.3: Create planet-cache directory (optional)
-STEP 7.4: Make sure that the logs subdirectory exists
-STEP 8: Review Roller configuration
-STEP 8.1: Review the WEB-INF/classes/roller.properties file
-Where to define custom properties
-STEP 8.2: Change keys in the WEB-INF/security.xml file
-STEP 9: Start Tomcat and start using Roller
-Appendix A: The WEB-INF/roller.properties file
+Introduction 3
-Introduction
+STEP 1: Before you install Roller 4
+STEP 2: Unpack the Roller distribution 5
+STEP 3: Create Roller tables in your database 6
+STEP 4: Install required third party jars 7
+ STEP 4.1: Install JDBC driver jar(s) 7
+ STEP 4.2: Install JavaMail and Activation jars 7
+STEP 5: Deploy Roller to your application server 8
+STEP 6: Check your internationalization settings 10
+STEP 7: Setup Roller data directories 11
+ STEP 7.1: Create uploads directory 11
+ STEP 7.2: Create search-index directory 11
+ STEP 7.3: Create planet-cache directory (optional) 11
+ STEP 7.4: Make sure that the logs subdirectory exists 12
+STEP 8: Review Roller configuration 13
+ STEP 8.1: Review the WEB-INF/classes/roller.properties file 13
+ Where to define custom properties 13
+ STEP 8.2: Change keys in the WEB-INF/security.xml file 14
+STEP 9: Start Tomcat and start using Roller 15
+
+Appendix A: Upgrading an existing Roller installation 16
+ STEP 1: Shutdown and backup your old Roller [#1] 16
+ STEP 2: Install the new Roller [#2] 16
+ STEP 3: Copy resources and update configs [#3] 17
+ 3.1 Copy your old resources and other files you've added 17
+ 3.2 Remove JavaMail jars if duplicated 17
+ 3.3 Review configuration properties 17
+ STEP 4: Upgrade the database [#4] 17
+ STEP 5: Startup your app server [#5] 18
+Appendix B: The WEB-INF/roller.properties file 19
+
+Introduction
This document describes how to install Roller in the following environment:
+Operating System: UNIX or Windows based operating system
+Java development kit: Java 2 SE 1.4 SDK (or later)
+Application server: Tomcat 5.X (or later)
+Relational Database: MySQL 4.X (or later)
-Operating System: UNIX or Windows based operating system
-Java development kit: Java 2 SE 1.4 SDK (or later)
-Application server: Tomcat 5.X (or later)
-Relational Database: MySQL 4.X (or later)
+NOTE: If you're upgrading from an earlier release of Roller, read Appendix B first
What do you need to know to install Roller? 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.
-
What about other servlet containers? 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.
-
What about other databases? These instructions target MySQL, but Roller also includes database setup scripts for PostgreSQL 7.X later, Apache Derby, IBM DB2, Oracle and HSQL-DB.
-
What platform combinations are known to work? For information on which platforms we can vouch for, see the the Platforms page on the Roller wiki.
STEP 1: Before you install Roller
-
Before you install Roller software you should install and configure the Java development kit, your application server and your database.
-
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.
-
For UNIX with bash shell:
% export CATALINA_HOME=/opt/jakarta-tomcat-5.0.29
@@ -69,7 +76,6 @@
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.
-
STEP 2: Unpack the Roller distribution
Pick a directory on your computer and unpack the Roller distribution using either GNU tar on UNIX or WinZip on Windows. Hereinafter, we'll refer to that directory as your Roller installation directory, $ROLLER in the UNIX examples or %ROLLER% in the Windows examples.
@@ -77,6 +83,7 @@
Here are some examples to show you how you might unpack Roller on your computer.
UNIX example
+
Assuming you download the distribution into your home directory and you'd like to install Roller into /usr/local you might do something like this:
% cd /usr/local
% tar xzvf ~/roller-2.1.tar.gz
@@ -84,8 +91,8 @@
That would create the Roller installation directory /usr/local/roller.
Windows example
-Use WinZip to extract the Roller distribution file into the directory of your choice for example, no example necessary.
+Use WinZip to extract the Roller distribution file into the directory of your choice for example, no example necessary.
STEP 3: Create Roller tables in your database
@@ -103,6 +110,7 @@
Here are some examples to show you how you might create the Roller tables in MySQL:
UNIX example:
+
% cd $ROLLER/WEB-INF/dbscripts/mysql
% mysql -u root -p
password: *****
@@ -114,7 +122,8 @@
mysql> quit
Windows example:
- C> cd %ROLLER%\dbscripts\mysql
+
+ C> cd %ROLLER%\WEB-INF\dbscripts\mysql
C> mysql -u root -p
password: *****
mysql> create database roller;
@@ -125,11 +134,8 @@
mysql> quit
NOTES
-
For MySQL, don't forget to call flush privileges to commit your changes to MySQL.
-
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):
-
mysql roller -h 127.0.0.1 -u scott -ptiger
@@ -148,7 +154,6 @@
C> copy mysql-connector.jar %CATALINA_HOME%\common\lib
NOTES
-
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 must use J/Connector/J 3.1.X then please read Installation FAQ page item #13 on the Roller wiki.
STEP 4.2: Install JavaMail and Activation jars
@@ -172,11 +177,13 @@
To deploy Roller to your application server you need to inform your application server:
- Where to find the Roller installation directory
- How to configure the Roller datasource under the JNDI name jdbc/rollerdb
+Where to find the Roller installation directory
+
+How to configure the Roller datasource under the JNDI name jdbc/rollerdb
For Tomcat you can do this by creating what's known as a context configuration file named roller.xml and placing that file in the Tomcat conf/Catalina/localhost directory.
+
Example context configuration file for Tomcat 5.0.X users
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.
@@ -241,10 +248,8 @@
NOTES
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 maxActive, maxIdle, and removeAbandoned values. Depending on your database configuration you may have to go pretty low, such as setting maxActive to 6, maxIdle to 3 and removeAbandonedTimeout to 60.
-
User scott@localhost has more than 'max_user_connections' active connections
-
STEP 6: Check your internationalization settings
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.
@@ -274,6 +279,7 @@
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.
STEP 7.1: Create uploads directory
+
By default, Roller saves uploaded files under the directory:
${user.home}/roller_data/uploads
@@ -282,19 +288,16 @@
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 uploads.dir in the roller.properties file. See step 8 for more information on the roller.properties file.
-STEP 7.2: Create search-index directory'
+STEP 7.2: Create search-index directory
By default, Roller creates and maintains its text search index data in files under the directory
${user.home}/roller_data/roller-index
-
Again, ${user.home} 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 search.index.dir in roller.properties. See step 8 for more information on the roller.properties file.
STEP 7.3: Create planet-cache directory (optional)
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. /var/roller/planet-cache).
-
The planet aggregator is off by default. To enable it, you'll have to override the planet.aggregator.enabled property (see the ConfigurationGuide). Once you've got Roller up and running, login (as an adminstrator), go to the Planet:Configuration page and set full-path to the directory you choose for the planet-cache.
-
Currently, you must specify the location of the planet-cache directory through the Roller web UI (but we planning to move it to roller.properties because it is really a startup property).
STEP 7.4: Make sure that the logs subdirectory exists
@@ -312,8 +315,7 @@
STEP 8.1: Review the WEB-INF/classes/roller.properties file
-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. NOTE: the default roller.properties file is shown in Appendix A.
-
+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. NOTE: the default roller.properties file is shown in Appendix B.
Where to define custom properties
There are three ways you can alter the default configuration for Roller.
@@ -348,9 +350,7 @@
STEP 8.2: Change keys in the WEB-INF/security.xml file
Starting with version 2.1, Roller uses the Acegi security infrastructure. Several of the security features rely on keys that are intended to be site-specific. These keys are used to compute HMAC (hash-based message authentication code) values for Remember Me cookies. Knowledge of these keys could allow an attacker to forge invalid cookies, and thereby gain unauthorized access to your Roller installation (at the application level).
-
Roller ships with default values, and these should assumed to be widely known. You should change your keys to be secret values specific to your own site.
-
Here is how to change the keys.
1.Find your WEB-INF/security.xml file and open it in a text editor.
@@ -358,30 +358,116 @@
3.For the beans with ids "rememberMeServices" and "rememberMeAuthenticationProvider" change the value field of the property with name="key" to be different from the default value of "rollerlovesacegi". You can use any string value of your choosing. It should be a secret specific to your site. Use the same key value in these two beans; they must match
NOTES
-
The reason one should change the anonymous provider key is that a granted authorities list is embedded within the anonymous authentication token.
-
STEP 9: Start Tomcat and start using Roller
Start your Servlet Container, open your web browser, browse to the Roller start page and start using Roller. If you are installing Roller on Tomcat then your Roller start page URL is probably http://localhost:8080/roller.
UNIX example
+
% cd $CATALINA_HOME/bin
% ./startup.sh
Windows example
+
C> cd %CATALINA_HOME%\bin
C> startup
NOTE: the first user you create will have administrator privileges, so make sure you create the first user yourself. An admin user can grant and revoke admin rights from other users.
You're done!
-
Roller should be working perfectly now. If not, then please consult the Installation FAQ page on the Roller wiki and then check with the experts on the Roller mailing lists. Somebody has probably encountered the very same problems that you are encountering.
+Appendix A: Upgrading an existing Roller installation
+
+This document describes how to upgrade an existing installation to the latest release of Roller by upgrading the Roller database and replacing the old Roller files (which are typically found in tomcat/webapps/roller) with the new release.
+The steps are:
+
+STEP 1: Shutdown and backup your old Roller
+STEP 2: Install the new Roller
+STEP 3: Copy old configuration
+STEP 4: Upgrade the database
+STEP 5: Startup Tomcat
+STEP 1: Shutdown and backup your old Roller [#1]
+
+Before you get started with your upgrade, you should shutdown your existing Roller install, make a backup of your data, and move the old Roller files out of the way. Here is an example of how you'd do this with a Tomcat/MySQL setup:
+Run shutdown.sh to stop Tomcat, for example:
+
+ % cd $CATALINA_HOME/bin
+ % ./shutdown.sh
+
+Backup your database to somewhere safe on your system or to a remote file-system, for example if you use MySQL you might do something like this:
+
+ % mysqldump -u scott -p rollerdb > \
+ /somewhere/safe/roller-backup-20050420.dmp
+
+Here's an example for PostgreSQL users:
+
+ pg_dump -h 127.0.0.1 -W -U scott rollerdb > roller.db
+
+Move your Roller files to somewhere safe, for example:
+
+ % cd $CATALINA_HOME/webapps
+ % mkdir /somewhere/safe/roller-old
+ % mv roller /somewhere/safe/roller-old
+
+STEP 2: Install the new Roller [#2]
+
+Follow the normal installation instructions to install Roller, except:
+Don't create a new database for Roller, instead point the new Roller to your old Roller database
+DO NOT start Tomcat when you are done with the installation, we'll do that later
+
+
+STEP 3: Copy resources and update configs [#3]
+
+3.1 Copy your old resources and other files you've added
+User uploaded files are, by default, stored in the /resources sub-directory of the Roller context directory. You should copy your old resources directory into your new Roller installation.
+For example, on UNIX you can use cp -r to copy the whole directory:
+
+ % cd %CATALINA_HOME/webapps/roller
+ % cp -r /somewhere/safe/roller-old/roller/resources .
+
+NOTE: If you have any new themes under roller/themes, make sure to copy those as well.
+
+3.2 Remove JavaMail jars if duplicated
+
+In an upgrade installation, you may already have the JavaMail jars mail.jar and activation.jar in your Tomcat common/lib. If so, you should remove them from the WEB-INF/lib directory within the web app. (Keep them only in the common/lib directory.)
+
+3.3 Review configuration properties
+
+Review properties as described in STEP #8 of the installation guide.
+
+STEP 4: Upgrade the database [#4]
+
+Use the appropriate database upgrade script to upgrade your database. To do this, login to your database and run one (or more) of the Roller upgrade scripts located in Roller's WEB-INF/dbscripts directory that corresponds to your database. There's a directory for MySQL, PostgreSQL, HSQLDB and more.
+The database script directories
+
+WEB-INF/dbscripts/mysql
+WEB-INF/dbscripts/postgresql
+WEB-INF/dbscripts/hsql
+and more...
+
+There is an upgrade script for each release of Roller. If you're upgrading from Roller 2.0, which was the last release before 2.1 you'll only need to run one script, that's 200-to-210-migration.sql. For example, here's how you'd do it for a MySQL database running on UNIX:
+
+ % cd $CATALINA_HOME/webapps/roller/WEB-INF/dbscripts/mysql
+ % mysql -u root -p
+ password: *****
+ mysql> use roller;
+ mysql> source 200-to-210-migration.sql
+ mysql> quit
+
+If you're upgrading from an earlier release you'll have to run each of the older scripts in order to upgrade your database.
+
+STEP 5: Startup your app server [#5]
+
+Use the standard Tomcat startup.sh (or startup.bat on Windows) script to start Tomcat. As Roller starts up, it will perform some final steps to upgrade your database, this may take few seconds longer than your average Roller startup.
+And you're done!
+
+If Roller doesn't come up, check the logs for exceptions and error messages. You should see these messages in the tomcat/logs/catalina.out file and in tomcat/logs/roller.log. If you still can't diagnose and fix your startup program, then subscribe to the Roller user mailing list for help. If there are any interesting messages in the log files, send those along too.
+
-Appendix A: The WEB-INF/roller.properties file
+Appendix B: The WEB-INF/roller.properties file
This file defines the default start-up properties for Roller. See step 8 for instructions on how to override the properties in this file.
Modified: incubator/roller/trunk/docs/installguide/roller-install-guide.odt
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/installguide/roller-install-guide.odt?rev=388209&r1=388208&r2=388209&view=diff
==============================================================================
Binary files - no diff available.
Modified: incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide.html
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide.html?rev=388209&r1=388208&r2=388209&view=diff
==============================================================================
--- incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide.html (original)
+++ incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide.html Thu Mar 23 08:51:02 2006
@@ -7,7 +7,7 @@
<META NAME="AUTHOR" CONTENT="Dave Johnson">
<META NAME="CREATED" CONTENT="20051209;11500200">
<META NAME="CHANGEDBY" CONTENT="Dave Johnson">
- <META NAME="CHANGED" CONTENT="20060211;9310400">
+ <META NAME="CHANGED" CONTENT="20060323;11315500">
<META NAME="SDFOOTNOTE" CONTENT=";;;;P">
<META NAME="SDENDNOTE" CONTENT="ARABIC">
<STYLE>
@@ -40,7 +40,7 @@
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=7 STYLE="font-size: 32pt"><B>Apache
Roller</B></FONT></P>
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=5 STYLE="font-size: 20pt"><B>Version
- 2.1-incubating</B></FONT></P>
+ 2.2-incubating</B></FONT></P>
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
</P>
<P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR>
@@ -774,23 +774,25 @@
</UL>
<P><BR><BR>
</P>
- <P><SPAN ID="Frame28" DIR="LTR" STYLE="float: left; width: 6.85in; height: 4.58in; border: none; padding: 0in; background: #ffffff">
- <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_58eca8b7.png" NAME="graphics11" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration
+ <P><SPAN ID="Frame28" DIR="LTR" STYLE="float: left; width: 6.85in; height: 5.23in; border: none; padding: 0in; background: #ffffff">
+ <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_9cad71a.png" NAME="graphics11" ALIGN=LEFT WIDTH=658 HEIGHT=477 BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration
8: Edit entries page</I></FONT></P>
+ <P STYLE="margin-top: 0.08in"><BR><BR>
+ </P>
</SPAN><BR CLEAR=LEFT><BR><BR>
</P>
- <H3>3.2.2 - <B>Finding old entries with the Create & Edit:Edit
- Entries page</B>
+ <H3>3.2.2 - <B>Finding old entries with the Create &
+ Edit:Entries page</B>
</H3>
<P STYLE="font-weight: medium">You can use the Create &
- Edit:Edit Entries to find and edit your old posts. That includes
- posts that have scrolled-off the bottom of the Pending, Draft and
- Recent Entries lists we discussed above. When you first arrive on
- the page it will show you most recent entries, as shown in the
- screenshot below. If you want to find an old post you can use the
- start and end date calendars to look for posts in a specific time
- period. You can edit any of the entries in the Weblog Entries list
- by simply clicking on its title.
+ Edit:Entries to find and edit your old posts. That includes posts
+ that have scrolled-off the bottom of the Pending, Draft and Recent
+ Entries lists we discussed above. When you first arrive on the page
+ it will show you most recent entries, as shown in the screenshot
+ below. If you want to find an old post you can use the start and
+ end date calendars to look for posts in a specific time period. You
+ can edit any of the entries in the Weblog Entries list by simply
+ clicking on its title.
</P>
<H3>3.2.3 - <B>Finding old entries using the pages of your weblog</B>
</H3>
@@ -1230,7 +1232,7 @@
settings on the screen-shot below (which needs to be updated to
Roller 2.1):
</P>
- <P><SPAN ID="Frame14" DIR="LTR" STYLE="float: left; width: 6.78in; height: 8.03in; border: none; padding: 0in; background: #ffffff">
+ <P><SPAN ID="Frame14" DIR="LTR" STYLE="float: left; width: 6.78in; height: 7.84in; border: none; padding: 0in; background: #ffffff">
<P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m3c68c547.png" NAME="graphics2" ALIGN=LEFT WIDTH=640 HEIGHT=728 BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration
14: Weblog settings page part 1</I></FONT></P>
<P STYLE="margin-top: 0.08in"><BR><BR>
@@ -2385,6 +2387,8 @@
<P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m31cb7c1f.png" NAME="graphics40" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration
24: Automatic ping configuration page</I></FONT></P>
</SPAN><BR CLEAR=LEFT><BR><BR>
+ </P>
+ <P><BR><BR>
</P>
<P>To enable automatic pings to a ping target, find the ping target
on the page and click the <B>Enable</B> link in the Automatic
Added: incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide_html_9cad71a.png
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide_html_9cad71a.png?rev=388209&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/roller/trunk/docs/userguide/generated/html/roller-user-guide_html_9cad71a.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/roller/trunk/docs/userguide/generated/roller-user-guide.pdf
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/userguide/generated/roller-user-guide.pdf?rev=388209&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/roller/trunk/docs/userguide/generated/roller-user-guide.pdf
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: incubator/roller/trunk/docs/userguide/roller-user-guide.odt
URL: http://svn.apache.org/viewcvs/incubator/roller/trunk/docs/userguide/roller-user-guide.odt?rev=388209&r1=388208&r2=388209&view=diff
==============================================================================
Binary files - no diff available.