Introduction

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

Java 1.3.1 SDK
Tomcat 4.0.3 Servlet Container
MySQL 3.2.3 database
Windows XP or Redhat 7.1 Linux

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. WebSphere, WebLogic, ...) and any JDBC-accessible database (e.g. Oracle, PostgreSQL, ...), but this document does not tell you how to do that.

Overview

1. Prerequisites. Before you get to Roller, make sure your Java 1.3 SDK, Tomcat 4.X 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 Servlet Authentication to use the Roller database tables. In this step, you will need to configure your Servlet Container's to authenticate users against the Roller USER and ROLE tables in the Roller database.

5. Configure Roller to use your database. Edit the Roller deployment and property files to insert your JDBC driver class name and URL.

6. 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.3.1, Tomcat 4.0, MySQL 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.3

Windows NT/2000/XP example

set CATALINA_HOME d:jakarta-tomcat-4.0.3

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

In this step you use an SQL script to create within your database the tables required to run Roller. We will assume you have a user named 'roller' with password 'tiger' who has all database privileges.

UNIX example

% cd $CATALINA_HOME/webapps/roller/WEB-INF
% mysql -u roller -p
password: *****
mysql> create database roller;
mysql> use database roller;
mysql> source createdb-mysql.sql
mysql> quit

Windows example

From an MS-DOS or Command Prompt window:

C> cd %CATALINA_HOME%webappsrollerWEB-INF
C> mysql -u roller -p
password: *****
mysql> create database roller;
mysql> use database roller;
mysql> source createdb-mysql.sql
mysql> quit

STEP 5: Configure Roller to use your database

Edit the Roller deployment and property files to insert your JDBC driver class name and URL. The Roller application includes the MySQL JDBC driver jar in the Roller WEB-INF/lib directory, so the MySQL JDBC driver is already in Roller's classpath. All you need to do is to make sure that the Roller deployment files velocity.properties and database.xml under WEB-INF point to your install of MySQL and use the right database username and password combinations.

For the Velocity configuration file <tomcat-dir>/webapps/WEB-INF/velocity.properties

Make sure that this file defines the following two properties correctly for your database. Look at the example below, it shows the two properties that must be set. You probably only need to change the username and password. If you want more information on the properties in the velocity.properties file see the documentation for the Velocity template engine.

database.resource.loader.resource.jdbc_class=org.gjt.mm.mysql.Driver
database.resource.loader.resource.jdbc_url=jdbc:mysql://localhost/rollerdb?user=roller&;password=tiger

For Castor JDO database configuration file <tomcat-dir>/webapps/WEB-INF/database.xml

Make sure that this file points to your MySQL database. Look at the example below, it shows the contents of the database.xml file. You probably only need to change the username and password. If you want more information on the properties in the database.xml file see the documentation for the Castor JDO persistence engine.

<database name="rollerdb" engine="mysql">
<driver class-name="org.gjt.mm.mysql.Driver"
url="jdbc:mysql://localhost/roller?user=roller&password=tiger">
</driver>
<mapping href="./mapping.xml"/>
</database>

STEP 5: Configure Servlet Authentication to use the Roller database tables

In this step, you will need to configure your Servlet Container's to authenticate users against the Roller USER and ROLE tables in the Roller database. In Tomcat you do this by editing the server.xml file in the Tomcat conf directory. Look for the section where security Realms are configured. Comment out whatever Realm is not already commented out and a yourself a new realm, similar to the one shown below.

<Realm className="org.apache.catalina.realm.JDBCRealm"
    debug="99" driverName="org.gjt.mm.mysql.Driver"
    connectionURL=
    "jdbc:mysql://localhost/roller?user=roller&password=tiger"
    userTable="user" userNameCol="username" userCredCol="password"
    userRoleTable="role" roleNameCol="role" />

The example above tells Tomcat to set up a JDBC realm using the MySQL JDBC driver, and a connection URL with user name “roller” and password “tiger”. The configuration also tells Tomcat which tables and columns hold username, password, and role information. You will probably need to change the connectionURL to include your own MySQL user name and password, but everything else should stay the same.

Also, put the MySQL JDBC jar in the Tomcat server/lib directory, so that the Tomcat JDBC Realm will have it in its classpath at authentication time.

UNIX example

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

Windows example

From an MS-DOS or Command Prompt window:

C> cd %CATALINA_HOME%webappsrollerWEB-INFlib
C> copy mm.mysql-2.0.11-bin.jar %CATALINA_HOME%serverlib

STEP 6: 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.

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

Velocity - http://jakarta.apache.org/velocity
Castor – http://castor.exolab.org
Mysql – http://mysql.com
JDK 1.3 – http://javasoft.com
Tomcat 4.0 – http://jakarta.apache.org/tomcat
Redhat Linux 7.1 – http://redhat.com
Windows XP – http://microsoft.com