dave's wiki

How to install Roller. Last updated for Roller 2.1

• Introduction
  • STEP 1: Prerequisites [1]
  • STEP 2: Unpack the downloaded ZIP or TAR file [2]
  • STEP 3: Create Roller tables in your database [3]
  • STEP 4: Download and install required jars [4]
  • STEP 5: Deploy Roller to your app server [5]
  • STEP 6: Setup app server for UTF-8 [6]
  • STEP 7: Setup Roller data directories [7]
  • STEP 8: Review Roller configuration [8]
  • STEP 9: Start Tomcat and Roller [9]
  • STEP 10: Finishing Touches [10]

See also:

• UserGuide exlains how to use Roller
• ConfigurationGuide explains how to configure Roller
• Upgrading from an earlier release: see the UpgradeGuide
• The Platforms lists the setups used by the Roller developers

Introduction#

Describes how to install Roller in the following environment:

• Operating System: UNIX or Windows based operating system
• Java development kit: Java 1.4.X SDK or later
• Application server: Tomcat 5.X or later
• Relational Database: A ~MySQL 4.X or later or PostgreSQL 7.X or later

What about other servlet containers? These instructions favor Tomcat, but with some expertise you should be able to make Roller work on any Servlet API 2.3 compatible Servlet Container (e.g. Weblogic, JBoss, WebSphere, Jetty, Resin, OrionServer, ...); Servlet API 2.4 support is recommended for sites requiring internationalization features. If you deploy Roller to a non-Tomcat server, please constribute your install notes to help others who might want to do the same.

What about other databases? These instructions favor MySQL, but Roller also includes database setup scripts for PostgreSQL and HSQL-DB. With some expertise you should be able to make Roller work on any JDBC accessible database (e.g. Oracle, Informix, Sybase, MS SQL Server, ...).

What platform combinations are known to work? For information on which platforms we can vouch for, see the Platforms page.

STEP 1: Prerequisites [#1]#

Before you install the Roller software you need to make sure you have installed your Java SDK, your Tomcat Servlet Engine, and your ~MySQL database installed and configured on your system.

As part of the Tomcat install, you should have set an environment variable called CATALINA_HOME as show in the example below. I'm telling you this now because later, in other examples in this guide we will refer to the CATALINA_HOME variable.

UNIX (csh) example

    % setenv CATALINA_HOME /opt/jakarta-tomcat-5.0.29

Windows example, from an MS-DOS or Command Prompt window:

    C> set CATALINA_HOME d:\jakarta-tomcat-5.0.29

Notes

• Make sure you enable UTF-8 support in MySQL (see page Setting Up UTF8 on MySQL for details).
• If you're running ~MySQL on Debian, make sure ~MySQL TCP/IP networking is enabled (see page DebianMySQL for details).

STEP 2: Unpack the downloaded ZIP or TAR file [#2]#

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-2.0-incubating.tgz $CATALINA_HOME/webapps
    % cd $CATALINA_HOME/webapps


    % tar xzvf roller-2.0-incubating.tgz

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

STEP 3: Create Roller tables in your database [#3]#

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/dbscripts directory.

• WEB-INF/dbscripts/mysql/creatdb.sql - creates tables for ~MySQL
• WEB-INF/dbscripts/hsql/creatdb.sql - creates tables for ~HSQL-DB
• WEB-INF/dbscripts/postgresql/creatdb.sql - creates tables for ~PostgreSQL

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

Make sure you enable UTF-8 support in MySQL (see page Setting Up UTF8 on MySQL for details).

UNIX example

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

Windows example, from an MS-DOS or Command Prompt window:

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

Notes:

~MySQL users, don't forget to call "flush privileges" and make sure that your MySQL installation hasn't set the skip-networking option. Connector/J can only access ~MySQL via TCP/IP. The ~MySQL command line tool however doesn't use TCP/IP sockets by default. To check whether your connect works, use anything other than "localhost" as host, for example:

    mysql roller -h 127.0.0.1 -u scott -ptiger

STEP 4: Download and install required jars [#4]#

You will need to download and "install" a couple of requred jars: JDBC driver jar(s) and the ~JavaMail jars.

Step 4.1: JDBC driver jar#

Roller uses the database connection pool provided by your application server, which you will configure in the next step. If your application server is to create database connections to your database, your application server will need the JDBC driver jar for that database.

For Tomcat, place your JDBC driver jar(s) in Tomcat's common/lib directory.

UNIX example: unzip and untar the MySQL Connector/J download into a directory, cd to that directory and then copy to Tomcat common/lib

    % cp mysql-connector.jar $CATALINA_HOME/common/lib

Windows example, from an MS-DOS or Command Prompt window: unzip the MySQL Connector/J download into a directory, cd to that directory and then copy to Tomcat common/lib

    C> copy mysql-connector.jar %CATALINA_HOME%\common\lib

Notes

• If you use the Connector/J 3.1.X series drivers with MySQL 4.1.X, then please read InstallationFAQs #13
• ~MySQL users can find the ~MySQL JDBC driver, known as Connector/J, on the Connector/J page of the ~MySQL web site.

Step 4.2: ~JavaMail and Activation jars#

Roller can be configured to send email notifications of comments. If this is to work, Roller needs ~JavaMail and Activation jars. Roller now includes these in the distribution. For Tomcat, you need to move (not copy) the files mail.jar and activation.jar from Roller's WEB-INF/lib directory to your CATALINA_HOME/common/lib, (removing them from the web app). Note that if you enable the mail functionality, these jars must be in the Tomcat common/lib directory and should be removed from the distribution WEB-INF/lib directory.

In order to enable the mail functionality, you will also need to include the section on the mail session resource in your context descriptor file, as described in the following sections, and in the Admin | Configuration page, you will need to enable the functionality for e-mailing comments.

STEP 5: Deploy Roller to your application server [#5]#

Deploy Roller to your J2EE application server. You have to do three things:

• Tell app server where to find Roller's install directory
• Tell app server to authenticate users against Roller database table rolleruser and userrole
• Configure a datasource for your database named jdbc/rollerdb

For Tomcat users, this means defining 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.

You can do this in one of two places:

• Within a Host element within your server.xml file conf/server.xml. Look for the section of the server.xml file where Contexts are defined add the Context configuration described below.

• Alternatively, you can place the Context configuration in a file named roller.xml in the CATALINA_HOME/conf/Catalina/localhost directory.

Example for Tomcat 5.0.X Users

If you are using Tomcat 5.0.X as a container use the example context definition from this section. If you are using Tomcat 5.5.X as a container, follow the example in the next section. There are some differences.

To avoid some browser-specific issues with displaying and cutting/and pasting this XML, we recommend that instead of cutting and pasting from this screen that you download the attached example context configuration for Tomcat 5.0 roller_tomcat_5_0.xml and edit the contents as described in the comments within that downloaded file.

The examples assume you are using MySQL. If you use an alternate database, you need to change the two jdbc URLs as appropriate for your database.

If you use the example here, make sure you replace scott/tiger with your MySQL username and password. If you use the example file, make sure you replace the names as described within the comments at the top of that file.

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

<Realm className="org.apache.catalina.realm.JDBCRealm"      
    driverName="com.mysql.jdbc.Driver" 
    connectionURL=
    "jdbc:mysql://localhost:3306/roller?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;mysqlEncoding=utf8"
    connectionName="scott"
    connectionPassword="tiger"
    userTable="rolleruser" 
    userNameCol="username" 
    userCredCol="passphrase" 
    userRoleTable="userrole" 
    roleNameCol="rolename" debug="0" />

<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>driverClassName</name>
       <value>com.mysql.jdbc.Driver</value>
    </parameter>
    <parameter>        
       <name>url</name>
       <value>
        jdbc:mysql://localhost:3306/roller?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;mysqlEncoding=utf8
       </value>
    </parameter>
    <parameter><name>username</name><value>scott</value></parameter>
    <parameter><name>password</name><value>tiger</value></parameter>
    <parameter><name>maxActive</name><value>20</value></parameter>
    <parameter><name>maxIdle</name><value>3</value></parameter>
    <parameter><name>removeAbandoned</name><value>true</value></parameter>
    <parameter><name>maxWait</name><value>3000</value></parameter>
</ResourceParams>

<!--
To enable email notification of comments: uncomment the resouce below, 
set your mailhost, and make sure you have mail.jar and activation.jar 
in <tomcat>/common/lib.
-->
<!--
    <Resource name="mail/Session" auth="Container" type="javax.mail.Session"/>
    <ResourceParams name="mail/Session">
        <parameter>
            <name>mail.smtp.host</name>
            <value>mailhost.example.com</value>
        </parameter>
    </ResourceParams>
-->

</Context>

Example for Tomcat 5.5.X Users

In Tomcat 5.5.X, you still place the context definition in either the server.xml file or in the conf/Catalina/localhost directory. However, the manner in which you define resource parameters has changed. For Tomcat 5.5.X, resource parameters must be defined as attributes on the Resource element; the ~ResourceParams element is not supported. You can use the following example as a starting point for your configuration. This is for Tomcat 5.5.X only; for Tomcat 4.X and 5.0.X containers, use the form shown in the previous section.

To avoid some browser-specific issues with displaying and cutting/and pasting this XML, we recommend that you download the attached example context configuration for Tomcat 5.5 roller_tomcat_5_5.xml.

If you use the example here, make sure you replace scott/tiger with your MySQL username and password. If you use the example file, make sure you replace the names as described within the comments at the top of that file.

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

<Realm className="org.apache.catalina.realm.JDBCRealm"      
    driverName="com.mysql.jdbc.Driver" 
connectionURL="jdbc:mysql://localhost:3306/roller?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;mysqlEncoding=utf8"
    connectionName="scott"
    connectionPassword="tiger"
    userTable="rolleruser" 
    userNameCol="username" 
    userCredCol="passphrase" 
    userRoleTable="userrole" 
    roleNameCol="rolename" debug="0" />

<Resource name="jdbc/rollerdb" auth="Container" type="javax.sql.DataSource"
  driverClassName="com.mysql.jdbc.Driver"
  url="jdbc:mysql://localhost:3306/roller?autoReconnect=true&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;mysqlEncoding=utf8"
  username="scott"
  password="tiger"
  maxActive="20"
  maxIdle="3"
  removeAbandoned="true"
  maxWait="3000" />

<!--
To enable email notification of comments: uncomment the resouce below, 
set your mailhost, and make sure you have mail.jar and activation.jar 
in <tomcat>/common/lib.
-->
<!--
    <Resource name="mail/Session" auth="Container" type="javax.mail.Session"
       mail.smtp.host="mailhost.example.com" />
-->

</Context>

Context Configuration Notes

• The first part of the <Context> configuration above sets up an Authentication <Realm> for Tomcat. This allows Tomcat to check a user's login credentials (username and password) against a table in the Roller database. Here, we configure Tomcat to use the rolleruser and role tables in the Roller database. For more information on configuring this see the Tomcat docs for JDBC Realm.

• Starting with Roller version 2.1, you do not need the Realm configuration setup in the Context. If you are using Roller version 2.1 or higher, you can comment that out.

• The second part of the <Context> configuration sets up the Roller Data Source as a <Resource>. Here you'll have to repeat some of the connection parameters that you entered in the <Realm> setup.

• The ampersand '&' character is used to identify entity references in XML, so you'll have to change the '&user=scott&password=password' to '&user=scott&password=password' in the connectionURL to avoid parsing exceptions while starting Tomcat. -- i.e. add 'amp;' after '&' --

• If you are not using MySQL or if you are using the newer MySQL Connector/J JDBC driver, 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.

• If Roller begins to fail and you see an error message similar to "User scott@localhost has already more than 'max_user_connections' active connections" in your logs (roller.log), try dropping your maxActive, maxIdle, and removeAbandoned values. Depending on your database configuration you may have to get draconion, such as setting maxActive to 6, maxIdle to 3, and removeAbandonedTimeout to 60.

STEP 6: Configure your application server for UTF-8 [#6]#

Roller's approach to internationalization (I18N) is to do everything in UTF-8. If you want I18N to work properly, you'll need to configure your application server and your web server to use UTF-8 encoding.

Web application server URI encoding
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.

Example: In Tomcat, the URI Encoding is specified in the Connector of the server.xml file:

<Connector port="12345" 
           enableLookups="false" 
           URIEncoding="UTF-8" 
           redirectPort="8443" 
           debug="0"
           protocol="AJP/1.3" />

Note: You need to do this for every connector through which you use Roller. For example, if you use the HTTP connector directly rather than AJP and Apache, you would need to add the URIEncoding="UTF-8" attribute to that Connector element as well, and similarly for the HTTPS connector if you use that.

Web server page encoding.
If you use a separate web server like Apache to render static content, make sure the page encoding of the web server is set to UTF-8.

Example: In case of Apache 2.x, use the ~AddDefaultCharset directive.

AddDefaultCharset utf-8

STEP 7: Setup Roller data directories [#7]#

Roller needs to store search-index, cache and log files to disk. So before you run Roller you need to ensure that Roller's data directories are created and are writable by the Roller process. By default Roller uses the following directory structure:

Step 7.1: Create uploads directory#

By default, Roller saves uploaded files under the directory ${user.home}/roller_data/uploads . Here ${user.home} is the Java system property that normally evaluates to the home directory of the user identity executing the server's JVM process.

In most cases, this default will probably work fine for you. However, for security reasons, some Tomcat installations (and other containers as well) 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 site, override the property uploads.dir in roller.properties (see ConfigurationGuide for details).

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 . Here ${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 ConfigurationGuide for details).

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#

The roller.log file is written to the location ${catalina.base}/logs/roller.log". 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.

STEP 8: Review Roller configuration [#8]#

You can configure much of Roller through the Roller web UI, but there are a set of configuration properties that must be defined at startup. Before you startup Roller for the first time, you should review these properties. You may be perfectly happy with the default configiuration, but if you're not then you can change it.

Please review the default startup configuration properties shown in the Configuration Guide and decide if you want to override any of them. Once you've done that you're ready to start Roller.

STEP 9: Start Tomcat and Roller [#9]#

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, from an MS-DOS or Command Prompt window:

    C> cd %CATALINA_HOME%\bin
    C> startup

You are done! Roller should be working perfectly now. If not, then please consult the InstallationFAQs and then check with the experts on the Roller mailing lists. Somebody has probably encountered the very same problems that you are encountering.

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.

Step 10: Finishing touches [#10]#

Now that have installed Roller and verified that it is working, there are some other steps you might wish to take.

• Configure Roller to run at an alternate URI
• Configure Secure Logins

Important Security Note for Roller versions 2.1 and higher#

For Roller versions 2.1 and higher, you should change the keys in the WEB-INF/security.xml to your own site-specific secrets before making your site public. These keys are used to compute hashed message authentication code values on cookies. Using the default values could expose your site to forged logins.

• For Roller 2.1 and higher. Change keys in the security.xml