mvnForum User Documentation

Cord Thomas

Software Architect
Lupine Information Systems

8 June 2003

Revision History
Revision v0.0.108 June 2003cat
Prepared documentation for RC1 with installation and user instructions.
Revision v0.0.2027 Dec 2003cat
Prepared installation documentation updates for RC2.
Revision v0.0.3018 April 2004cat
Updated for new features in RC3.

Table of Contents

  1. Foreward
  2. 1. Installation
    1. System requirements
    2. Application Server
      1. Apache Tomcat Application Server
      2. Caucho Resin Application Server
      3. Weblogic Application Server
      4. Other...
    3. Database Server
      1. First-Time Database Installation
      2. Database Upgrades
      3. MySQL
      4. postgreSQL
      5. Microsoft SQL Server
      6. Oracle
      7. SAPDB
      8. hsqldb
      9. Other...
    4. Setup Administrator Control panel
    5. Troubleshooting
    6. Versions

Foreward

Online documentation provides a HowTo approach to installing, administering and using mvnForum successfully. If you do not see what you are looking for here, take a look at the FAQ section, carefully compiled for your edification.

Chapter 1. Installation

System requirements

mvnForum has the following system requirements:

  • Any App Server supports Jsp 1.2 and Servlet 2.3 (mvnForum will not run on JSP 1.1/Servlet 2.2 Containers such as Tomcat 3, JRun 3 and Orion App Server because it does not fully support JSP 1.2/Servlet 2.3 protocols.

  • JDK 1.3 or later

  • A JDBC 2.0-compliant database (see the section called “Database Server” for list of supported databases (this release includes 4 drivers: mm.mysql, Connector/J, postgreSQL and hsqldb)

Application Server

Follow these steps to setup the application server.

  • Create a home folder for mvnForum, which MUST NOT be accessible from the web. This mvnForumHome folder is VERY IMPORTANT; it is where mvnForum will store uploaded attachments and the Lucene search index. mvnForum will not run if you do not configure this properly.

  • Unzip the distributed zip file into this folder.

  • Create a context in your app server. See the application server-specific configuration options for your server.

  • In the extracted folder, find the dir webapp\WEB-INF\classes. There are several properties files here. Open each file in a text editor and change the configuration parameters to appropriate values. In each property file are the instructions for the parameters in the configurations.

    [Note]Note

    Set database parameters to the correct values. Database server-specific information is presented the section called “Database Server” and also in the header of the sql script file.

    [Note]Note

    Currently you have to restart your App Server if you make changes in properties files (if not, your new config cannot take effect)

  • Copy the content of webapp dir in the extracted folder to the context dir that you have created above.

  • If you dont need some language support, just delete the folder for that language

    Ex: If you dont need Vietnamese support (locale is vi), delete the folder for that language webapp/mvnplugin/mvnforum/user/vi

  • If you would like to change the default language of mvnForum, just copy and overwrite the content of your preferred locale to this folder webapp/mvnplugin/mvnforum/user

    Ex: to change the default language from English to Vietnamese (locale is vi), just copy all files from webapp/mvnplugin/mvnforum/user/vi to webapp/mvnplugin/mvnforum/user

Apache Tomcat Application Server

Following is tomcat-specific application server setup configuration information:

  • To create a context, create a folder beneath tomcat/webapps (for example : mvnforum). This dir (context) MUST be in lower case (such as mvnforum) and is considered the root context for this web application.

  • For additional information on Tomcat contexts, visit the Apache Tomcat site

Caucho Resin Application Server

Following is resin-specific application server setup configuration information: Following is a directory layout for a mvnForum installation in the ROOT context (where the <resin-root> is /var/www):

  • <resin-root>/mvnplugin

  • <resin-root>/mvnplugin/mvnforum (contains all JSP files)

  • <resin-root>/mvnplugin/WEB-INF (created by RESIN)

  • <resin-root>/WEB-INF/

  • <resin-root>/WEB-INF/web.xml (see below)

  • <resin-root>/WEB-INF/listitemb/

  • <resin-root>/WEB-INF/lib/commons-beanutils.jar, commons-logging.jar, mvnforum.jar, myvietnam.jar (activation.jar, jndi.jar, mail.jar, and servlet.jar are in /resin/lib because they are globally used)

  • <resin-root>/WEB-INF/classes/

  • <resin-root>/WEB-INF/classes/*.properties files (7 files)

Snippet of web.xml:


            <servlet-mapping>
               <servlet-name>ForumUserServlet</servlet-name>
               <url-pattern>/brds/*</url-pattern>
            </servlet-mapping>
            <servlet-mapping>
               <servlet-name>ForumAdminServlet</servlet-name>
               <url-pattern>/mvnforumsadmin/*</url-pattern>
            </servlet-mapping>
          

This results in an application that maps to:    http://<host name>/brds/index

Weblogic Application Server

Following are notes on installing/configuring mvnForum in a WebLogic 7.0 context:

  • Copy the files from the webapps folder that came with mvnForum distribution into the weblogic applications directory and deploy it using the WLS console.

  • Setup the database (MySql as an example) by creating a connection pool with these parameters

    • name: mySQLConnectionPool

    • URL: jdbc:mysql://localhost/mvnforum

    • driver: org.gjt.mm.mysql.Driver

    • properties: user=mvnforum

    • password=mvnforum

    • number of connections: 10 (your choice here)

  • Create a datasource for this pool

    • name: mySQLDataSource

    • JNDI Name: mySQLDataSource

    • Pool Name: mySQLConnectionPool

  • Do not forget to add the driver in the server classpath.

  • Change the mvnplugin_mvnforum_MVNForumConfig.properties file to point to your application mvnforum and mvnplugin_mvnforum_ParamOptions.properties to identify the context name (the name of the web application you deployed in the console).

  • In mvncore_db_DBOptions.properties, comment out all entries but USE_DATASOURCE = true and DATASOURCE_NAME=mySQLDataSource.

[Note]Note

The only change noted to upgrade from WLS 7 to 8 is to change the ACL from mySQLConnectionPool to weblogic.jdbc.connectionPool.mySQLConnectionPool

Other...

Database Server

First-Time Database Installation

Follow these steps to setup the mvnForum database schema and prepare the data tables with seed forum data. See the following section on Upgrades for documentation on how to perform database-related upgrades from previous verions.

[Note]Note

Before running database scripts, we highly recommend that you back up all your data.

[Note]Note

The database-specific notes and installation/configuration guidelines are presented in the header of each of the appropriately named .sql files (sql/mvnForum_<supported database server>.sql). We urge you to to read and follow these guidelines carefully, because it may help you avoid possible database-specific problems

  • In the extracted folder, find the file sql/mvnForum_<supported database server>.sql

  • Create a database and confirm the correct database parameters have been set in the application server configuration step

  • Run the script. Please see the documentation for your database server for details on how to run sql scripts. Details on the sql scripts are presented in the database server-specific sections below.

  • Copy the jdbc driver for your database to the WEB-INF/lib folder of your context in step 3 above. (Note that this release includes 4 drivers for MySQL, postgreSQL and hsqldb)

[Note]Note

mvnForum includes an embedded database for hsqldb in folder sql/hsqldb, so you can copy this folder (hsqldb) to your mvnForumHome and set the proper config file mvncore_db_DBOptions.properties. This is the quickest way to get started with mvnForum

.

Database Upgrades

The following upgrade notes are provided to identify the database changes between versions and point to upgrade scripts where available. Remember, before running the script, we highly recommemd that you back up all your data.

General Upgrade Notes

To upgrade from beta1, beta2, beta3 or rc1 release, READ THE FOLLOWING NOTES CAREFULLY

  • Update the sql script first, please look at mvnforum\sql\upgrade

  • Backup your users' avatars in your App Server in this folder: mvnplugin\mvnforum\upload\memberavatars (The above folder is relative to the webapp dir of your App Server)

  • Back up all your config (.properties files) in your App Server in this folder: WEB-INF\classes(Backup this is for reference only) (The above folder is relative to the webapp dir of your App Server)

  • Delete your current servlet context of mvnForum before continueing the setup

  • In step 3 below, you MUST re-config your properties files (Note: There are several changes in properties files, so you cannot reuse the properties files in the beta1/beta2/beta3/rc1 release) Config the file log4j.properties for your logging (we highly recommend you config you log file to the log folder in mvnForumHome)

  • After setting up successfully, restore the avartars that you have backuped above

  • Run and test if mvnForum can run properly, and confirm the mvnForumHome has been configured properly

  • Rebuild the Lucene index for your forum before user can search on your forum: Admin Index -> Miscellaneous Tasks -> Rebuild Lucene Search Index Note: you dont have to rebuild Lucene index if upgrade from RC1

If you have a problem with the upgrade, post a message to the Installation and Upgrade forum at http://www.mvnForum.com. Include informatoin about your platform, your current installed version, and the specific error message(s) you are getting.

Beta1/Beta2 to Beta3

The database from the beta1 and beta2 schema changed on the upgrade to beta3:

  • Updated database schema - mvnformForum table's unique index changed from ForumName to ForumName and CategoryID

Use this script to upgrade to beta 3 (for mySQL and other databases that support this): sql\upgrade\1_0_0_beta2_to_1_0_0_beta3\mvnForum_update_mysql.sql. Modify this file to suit your database requirements

Beta3 to Release Candidate 1

The database from the beta3 schema changed on the upgrade to RC1:

  • Added two tables to the schema: mvnforumWatch and mvnforumAttachment

Use this script to upgrade from beta 3 to rc1 (find scripts for each supported database server): sql\upgrade\1_0_0_beta3_to_1_0_0_rc1\mvnForum_update_mysql.sql. Modify this file to suit your database requirements

MySQL

Some key points to using MySQL as the database for persisting forum threads

  • Driver: com.mysql.jdbc.Driver or org.gjt.mm.mysql.Driver

  • Url: jdbc:mysql://localhost/<database server>?useUnicode=true&characterEncoding=utf-8

  • Additional resources:

postgreSQL

Some interesting tidbits about storing the forum discussions in the postgreSQL database

  • Driver: org.postgresql.Driver

  • Url: jdbc:postgresql://<database host name>:<host port>/<database name>

    [Note]Note

    you should use jdbc driver version 7.3 or later

  • Additional information repositories:

Microsoft SQL Server

Some commercial notes about a commercial product

  • Driver: com.microsoft.jdbc.sqlserver.SQLServerDriver

  • Url: jdbc:microsoft:sqlserver://<database host name>:<port>;DatabaseName=<database name>[;property=value...]

    [Note]Note

    There is a service pack available for SQL Server 2000 JDBC driver, release 1/2003.

  • Points of interest for Microsoft's database server solution:

Oracle

Let the wisedom of the oracle guide you with this one

  • Driver (both 8 and 9i): oracle.jdbc.driver.OracleDriver

  • Url: jdbc:oracle:thin:@<database host name>:1521:<database name>

    [Note]Note

    Note: If your jdbc driver is before 8.1.7, you MUST upgrade jdbc driver to 8.1.7 or later (You dont have to upgrade Oracle database, just upgrade jdbc driver) mvnForum will not run on Oracle's jdbc driver before 8.1.7

  • Links from o to q:

SAPDB

 

In 2001 the source code for SAPdb was released to the general public, completing SAP's roadmap for releasing their database software under a GNU/GPL user license. By doing this SAP has brought a fully-featured, enterprise-class database system to the open source community. SAP continues to update and support SAPdb through their website (www.sapdb.org) and an active mailing list (www.sapdb.org/sap_db_contact.htm).

There are no limitations on database sizes or on the number of users. SAPdb is ACID compliant (fully supports ISO-SQL 92 Standards) and includes all RDBMS and enterprise features expected in an open DBMS such as Views, triggers, foreign keys, constraints of various kinds, stored procedures, versioning, hot backups, etc. From web

 
--Aaron Holmes 

Don't let the strain sap you of your energy, read on to glean key points on this database

  • Driver: com.sap.dbtech.jdbc.DriverSapDB

  • Url: jdbc:sapdb://<database host name>/<database name>

    [Note]Note

    JDBC driver (sapdbc.jar) is typically found in the $SAPDB_HOME/dep/misc directory of your installed SAPDB software. Be sure this is in the classpath visible to mvnForum

  • Links from o to q:

hsqldb

 

hsqldb is a relational database engine written in Java, with a JDBC driver, supporting a rich subset of ANSI-92 SQL (BNF tree format). It offers a small (less than 160k), fast database engine which offers both in memory and disk based tables. Embedded and server modes are available. Additionally, it includes tools such as a minimal web server, in-memory query and management tools (can be run as applets) and a number of demonstration examples.

 
--http://hsqldb.sourceforge.net/ 

  • Driver: org.hsqldb.jdbcDriver

  • Url: jdbc:hsqldb:<database name>

    Example: if your MVNFORUM_HOME is c:\mvnForumHome and you copy the folder hsqldb (in the sql folder) to the mvnForumHome folder, then your url is:

    DATABASE_URL = jdbc:hsqldb:c:\\mvnForumHome\\hsqldb\\mvnforum

  • User: sa

  • Pasword:

  • [Note]Note

    Due to strange behaviour of hsqldb's IDENTITY column (begin with 0 instead of 1) then you cannot reply to the first post, which has id = 0 in this case. If you know how to start an IDENTITY column with 1, please let me know.

    Read more on http://sourceforge.net/forum/forum.php?thread_id=838632&forum_id=73673

  • Links on help with hsqldb:

Other...

Setup Administrator Control panel

The administrator's control panel comprises a set of tools for managing the forums and users related to this context/installation of mvnForum. When you have succesfully installed the forum, there are, by default, 2 links

If you install in a context other than ROOT context, the url looks like this

  • home for mvnForum - http://www.[yourserver].com/[yourcontext]/mvnforum/index

  • Administrator Control Panel - http://www.[yourserver].com/[yourcontext]/mvnforumadmin/index

If you install in the ROOT context, the url look likes this

  • home for mvnForum - http://www.[yourserver].com/mvnforum/index

  • Administrator Control Panel - http://www.[yourserver].com/mvnforumadmin/index

Go to the Admin Zone and enter username = admin and password = admin

If Login successfully, click a Test System Configuration to check the config (If you deploy on a Linux/Unix box, Image Processing might not been supported)

The index page you see when you login also give you other info, including database and system info

Go to the Admin Zone and enter username = admin and password = admin

Change the password and edit your profile by clicking Forum Index -> MyProfile

Click Forum Management to create categories/forums for your community

You can create new users and set permissions for these new users

Troubleshooting

Following are some helpful thoughts on what to do and where to look if you are having troubles with setting up or using mvnForum after your installation/upgrade

Basic reminders

  • Make sure you meet the system requirements

  • Make sure you have read this installation guide carefully

  • Make sure you setup from the binary distribution package, not the source distribution package. If you have the source package, please see read the build instructions

  • Make sure you have read the short database guide in sql/mvnForum_<database>.sql carefully

Error messages

  • Error executing SQL in MVNForumPermissionWebHelper.getPermissionsForGroupGuest

    It means you have not configured your database properly. BEFORE printing this error in the stacktrace mvnForum also prints other information that details the EXACT DATABASE PROBLEM. Please review the stacktrace, it and find a string beginning with:

    Can't create a new connection in DBConnectionPool. URL = ....

    You can configure the log4j.properties to log all messages to file and use this file to find your database problem

  • Cannot upload an avatar to the server

    This is most likely an image support problem, please search the mvnForum for keyword headless

  • Error says 'Cannot update table Thread where primary key = (3)

    This is probably a database driver issue. Some drivers do not properly support the JDBC standards needed by mvnForum. See this thread for more

Remember, you can now search the mvnForum online to see if someone else has dealt with the problem you are facing.

If all else fails...gather this information and post a question

  • Your mvnForum version (such as rc1, build 24 April 2003)

  • Your OS version (Such as Windows 2000 service pack 2)

  • Your App Server version (Such as Tomcat 4.1.24)

  • Your Database version (Such as Mysql 3.23.51)

  • Your JDBC driver version (Such as mysql-connector-java-3.0.8-stable-bin.jar)

  • Your mvnForum .properties files content

  • Any stacktrace that you found

  • Any other information that you think useful to solve the problem

Versions

mvnForum documentation created using docbook.