The Roller Weblogger

Version 0.9.6 Installation Guide

Copyright © 2002 David M Johnson
Updated: October 7, 2002

Introduction

This document describes how to install the Roller weblogger on the Tomcat Servlet Engine and assumes the following configuration.

If you have more recent versions of the above software, don't worry – Roller will probably work fine. If you have older versions of the above software, you may have problems. Roller will not work on Tomcat 3.X, but older versions of Java and MySQL may work fine for Roller.

You should be able to make Roller work on any Servlet API 2.3 compatible Servlet Container (e.g. Resin, Orion, WebSphere, WebLogic, ...) and any JDBC-accessible database (e.g. Oracle, Informix, ...), but this document does not tell you how to do that.

Overview

1. Prerequisites. Before you get to Roller, make sure your Java SDK, Tomcat Servlet Container, and MySQL database are correcly installed on your system.

2. Unpack the downloaded ZIP or TAR file. In this step, you unpack the ZIP or TAR file that downloaded into your Servlet Container's web application deployment directory.

3. Create Roller tables in your database. In this step you use an SQL script to create within your database the tables required to run Roller.

4. Configure Roller's Servlet Context. Edit the Tomcat configuration file to add a Servlet Context to do Servlet Authentication against the Roller database, and configure a connection pooling datasouce for access via JNDI.

5. Make JDBC driver available to Tomcat. To support Servlet Authentication that you configured in step 4, you must place your JDBC driver jar(s) in Tomcat's common/lib directory.

6. Configure Roller before start-up. Review the Roller configuration settings in Roller's web.xml before you start Roller.

7. Start your Servlet Container and your database. Start your Servlet Container, open your web browser, browse to the Roller start page and start using Roller.

Six steps to installing Roller

STEP 1: Prerequisites

You need to JDK 1.4, Tomcat 4.0.5, either a MySQL, Postgres or HSQL database; and either Windows NT/2000/XP or UNIX

Make sure all these prerequisites are installed, configured and ready to go before you begin the install

As part of the Tomcat 4.0 install, you should have set an environment variable called CATALINA_HOME

UNIX (csh) example

setenv CATALINA_HOME /opt/jakarta-tomcat-4.0.5

Windows NT/2000/XP example

set CATALINA_HOME d:\jakarta-tomcat-4.0.5


STEP 2: Unpack the downloaded ZIP or TAR file

In this step, you unpack the ZIP or TAR file that downloaded into your Servlet Container's web application deployment directory. Tomcat's deployment directory is located in the webapps directory of the Tomcat install directory.

UNIX example

% cp roller.tgz $CATALINA_HOME/webapps
% cd $CATALINA_HOME/webapps
% tar xzvf roller.tgz

Windows example

Use WinZIP to extract roller.zip into %CATALINA_HOME%\webapps


STEP 3: Create Roller tables in your database

Now you need to create a new database, create a user with appropriate privileges, and use an SQL script to create the database tables required to run Roller.

To do this, login to your database and run one of the Roller database creation scripts located in Roller's WEB-INF directory:

createdb-mysql.sql - creates tables for MySQL
createdb-hsql.sql - creates tables for HSQL-DB
createdb-postgres.sql - creates tables for Postgres

The examples below show you how you might do this using MySQL, assuming your Roller user will have username roller and password tiger. For more information on MySQL, refer to the MySQL Reference Manual.

UNIX example

% cd $CATALINA_HOME/webapps/roller/WEB-INF
% mysql -u roller -p
password: *****
mysql> create database roller;
mysql> grant all on roller.* to roller identified by 'tiger';
mysql> use roller;
mysql> source createdb-mysql.sql
mysql> quit

Windows example

From an MS-DOS or Command Prompt window:

C> cd %CATALINA_HOME%\webapps\roller\WEB-INF
C> mysql -u roller -p
password: *****
mysql> create database roller;
mysql> grant all on roller.* to roller identified by 'tiger';
 mysql> use roller;
mysql> source createdb-mysql.sql
mysql> quit

NOTES:

If you are upgrading from Roller 0.9.5 you can upgrade your database using one of the 095-to-096-micrgration.sql scripts. This is a risky operation so you should backup your database before you run the migration script. The migration script will save the old Roller tables with names that start with "temp_" and you should not drop these backup tables until you are satisfied that your data base made it through the migration.

If you are upgrading from Roller 0.9.4, then run the 094-to-095 migration script and then the 095-to-096 migration script.

STEP 4: Configure Roller's Servlet Context

Edit the Tomcat Servlet engine's conf/server.xml configuration file to add a the Roller Servlet Context. This is where you configure the Servlet Authentication to use the Roller database tables and where you configure the Roller datasource. Look for the section of the server.xml file where Contexts are defined and assuming that you are using MySQL you should add the following:

<Context path="/roller" docBase="roller" debug="0">

<!-- Config Servlet Authentication to use Roller's USER and ROLE tables -->
<Realm className="org.apache.catalina.realm.JDBCRealm"
debug="0" driverName="org.gjt.mm.mysql.Driver"
connectionURL=
"jdbc:mysql://localhost/roller?autoReconnect=true&amp;user=roller&amp;password=tiger"
userTable="rolleruser" userNameCol="username" userCredCol="password"
userRoleTable="role" roleNameCol="role" />

<!-- Config datasource to be bound to java:comp/env/jdbc/rollerdb -->
<Resource name="jdbc/rollerdb" auth="Container"
type="javax.sql.DataSource"/>

<ResourceParams name="jdbc/rollerdb">
<parameter>
<name>factory</name>
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
<parameter><name>maxActive</name><value>30</value></parameter>
<parameter><name>maxIdle</name><value>30000</value></parameter>
<parameter><name>maxWait</name><value>100</value></parameter>
<parameter><name>username</name><value>roller</value></parameter>
<parameter><name>password</name><value>tiger</value></parameter>
<parameter>
<name>driverClassName</name><value>org.gjt.mm.mysql.Driver</value>
</parameter>
<parameter>
<name>url</name><value>jdbc:mysql://localhost/roller?autoReconnect=true</value>
</parameter>
</ResourceParams>

</Context>

NOTES:

If you are not using MySQL, then you will have to substitute the appropriate JDBC connection parameters (driver class name and connection URL) for your database.

For more information on Tomcat's server.xml configuration file, refer to the Tomcat Configuration Reference.


 STEP 5: Make JDBC driver available to Tomcat

To support Servlet Authentication that you configured in step 4, you must place your JDBC driver jar(s) in Tomcat's common/lib directory. The MySQL driver jar is include in the Roller distribution so for MySQL you might do this as follows:

UNIX example

% cd $CATALINA_HOME/webapps/roller/WEB-INF/lib
% cp mm.mysql-2.0.12.bin.jar $CATALINA_HOME/common/lib

Windows example

From an MS-DOS or Command Prompt window:

> cd %CATALINA_HOME%\webapps\roller\WEB-INF\lib
> copy mm.mysql-2.0.12.bin.jar %CATALINA_HOME%\common\lib


STEP 6: Configure Roller before start-up

The Roller web.xml file includes the following configuration parameters. If in doubt, don't change these values - the defaults are pretty reasonable.

org.roller.rss.usePort - true if the item URLs created in by the RSS feature should include the Servlet engine's port number. The default is false, but you might want to turn this on if you are running Tomcat behind an Apache web server.

org.roller.new.user.allow - allow new users to be added to Roller. Defaults to true.

org.roller.admin.users - comma separated list of user names that will have administrative rights on the system.

org.roller.authenticationClass - class name of a class that implements org.roller.presentation.Authenticator and that should be used to authenticate users.  This allows you to plug in your own authentication system if you do not want to use Servlet Authentication.  See org.roller.presentation.DefaultAuthenticator for an example of how to write a plug-in authenticator for Roller.

org.roller.editorPages - comma separated list of JSP files in the /weblog directory that contain weblog editing interfaces.  See the editor-ekit.jsp and editor-text.jsp files for examples of how to write a plug-in editor for Roller.

org.roller.enableAggregator - true to enable the Roller aggregation features: the $macros.showNewfeed() macros, the Newsfeeds:Subscriptions page, and the Newsfeeds:ViewAll page.

org.roller.upload.enabled - true to enable file upload. Defaults to true.

org.roller.upload.maxFileMB - maximum size in megabytes of file that users are allowed to upload. Defaults to 1.

org.roller.upload.maxDirMB - maximum size in megabytes of each user's upload directory. Defaults to 4.

org.roller.upload.allow - comma separated list of file extensions allowed in upload directory. Defaults to jpg,jpeg,gif,png. Forbid and Allow are mutually exclusive so set only one of the two.

org.roller.upload.forbid - comma separated list of file extensions forbidden in the upload directory. Defaults to nothing.

org.roller.upload.dir - directory where files are to be uploaded, may end with a slash. Defaults to empty string which indicates that files will be uploaded to the /resources directory in the Roller Servlet Context.

org.roller.upload.path - URL path to upload directory, should not end with a slash. Defaults to /resources which works well when the upload directory default.


STEP 7: Start Tomcat and start using Roller

Start your Servlet Container, open your web browser, browse to the Roller start page and start using Roller.

UNIX example, starting Tomcat

% cd $CATALINA_HOME/bin
% ./startup.sh

Windows example, starting Tomcat

From an MS-DOS or Command Prompt window:

C> cd %CATALINA_HOME%\bin
C> startup


References