Proposal Easy Install

Abstract

The Roller installation process is unacceptably complex. It's having a negative impact on Roller adoption and distracting the Roller community on the user mailing list. We need to make it really easy to install Roller.

Requirements

• Easy installation, meaning:
  • Ask users to provide minimum information to get Roller up and running
  • Create and upgrade tables automatically for user
• Additionally:
  • It must be possible to disable automatic upgrade
  • It must be possible to specify DB and mail via properties or JNDI names

Issues: four options

and I'd like to fix that. I've been thinking about the problem for a couple of weeks now and I've talked to folks in Sun, at ApacheCon and JavaOne about the problem. I looked at configuration features in Tomcat and Glassfish. I also looked at installation instructions for popular Java webapps Confluence, JIRA, Liferay Portal and Blojsom. So far, I've identified four these options:

Option 1) Property file based configuration

• User puts JDBC and mail-session connection parameters in roller-custom.properties
• If no DB and mail properties found, Roller falls back to JNDI names
• Roller can create/upgrade tables as needed
• Pros:
  • Easy, just one properties file for all Roller configuration
• Cons:
  • To use JNDI, user still needs to configure resources

Option 2) Separate installer for each Servlet container / app server

• Installer prompts user for configuration parameters
• Installer sets properties or sets up JNDI resources
• Installer does all setup and deploys Roller
• Roller can create/upgrade tables as needed
• Pros:
  • Easy UI driven installation
  • Can support properties or JNDI resources
  • Complements option #1
• Cons:
  • Need to develop separate installer for each Servlet container / app server

Option 3) Standalone bundle with Roller, Servlet container / app server and database

• User downloads, unpacks, runs startup script... done!
• Pros:
  • Amazingly easy for user
  • We can steal creation script from Blogapps project for Roller, Derby, Tomcat bundle
    Cons:
  • We'll need a separate bundle for each server
  • Not a complete solution if user wants database other than one we bundle

Option 4) Roller completely handles it's own installation

• Roller prompts user for configuration parameters, does all setup
  • Creating JNDI data-source and mail-session if needed
  • Or creating property file for non-JNDI based installation
• Roller can create/upgrade tables as needed
• Pros:
  • Easy UI driven installation
  • Does everything!
• Cons:
  • Need to develop separate logic for each Servlet container / app server
  • May be difficult or impossible for some servers
  • May require application server jars in Roller's WEB-INF/lib directory

Consensus on the Roller dev list is that option #1 is a must have, #2 and #3 are nice to have and #4 is too complex.

Note that the options are not mutually exclusive. Once #1 is in place, #2 is easier to implement because all of the options can take advantage of property-based configuration and automatic database creation and update.

So, this proposal covers option #1 and those who wish to development #2, #3 and #4 installers can propose those separately.

Design for Option #1: Property file based configuration

List and describe new manager methods, Struts actions, JSP pages, macros, etc.

Here are the changes to be made to enable property based installation/configuration:

Change #1: New properties

mail.hostname: Host name of mail server for email notification features, if not present then Roller will fall back to JNDI mail-session.
installation.auto: True to enable automatic creation and upgrade of database tables.
JDBC properties: We've already got JDBC connection properties in roller.properties, we just need to make small changes to how we use them.

Change #2: Change implementations of the Roller interface (Hibernate and JPA backends)

When creating persistence strategy:

• If JDBC connection properties present, use them
  • Save errors in Servlet context attributes so we can show them later
• Else use JNDI data-source
  • Save errors in Servlet context attributes so we can show them later

Change #3: Change mail sending code

When creating mail-session

• If mail-host property is present, use it
• Else use JNDI mail-session

Change #4: Change RollerContext initialization

• Don't throw RuntimeException on DB connection error
• Instead, allow context to load so we can show error/upgrade pages to user
• Only run upgradeDatabaseIfNeeded if installation.auto option is false

Change #5: Add DatabaseStatusFilter that checks database configuration

• If DB connection fails
  • If installation.auto, show error page to explain what went wrong and how to fix it
  • Else, show simple error/maintenance page
• If DB does not have tables
  • If installation.auto, show table creation page/action
  • Else, show simple error/maintenance page
• If DB is older version
  • If installation.auto, show database upgrade page/action
  • Else, show simple error/maintenance page

Change #6: Table creation page/action

• Tell user that tables need to be created, offer to create them
• Create tables, show user output from running creation script
• Ask user to redeploy or restart server

Change #7: Table upgrade page/action

• Tell user that tables need to be updated, offer to upgrade them
• Upgrade tables, show user output from running upgrade script
• Ask user to redeploy or restart server

Comments

Please comment on the dev mailing-list.