8 June 2003
| Revision History | ||
|---|---|---|
| Revision v0.0.10 | 8 June 2003 | cat |
| Prepared documentation for RC1 with installation and user instructions. | ||
| Revision v0.0.20 | 27 Dec 2003 | cat |
| Prepared installation documentation updates for RC2. | ||
| Revision v0.0.30 | 18 April 2004 | cat |
| Updated for new features in RC3. | ||
Table of Contents
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.
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)
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]](images/note.png)
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 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
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
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
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 |
|---|---|
The only change noted to upgrade from WLS 7 to 8 is to change the ACL from mySQLConnectionPool to weblogic.jdbc.connectionPool.mySQLConnectionPool | |
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 |
|---|---|
Before running database scripts, we highly recommend that you back up all your data. | |
| 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 |
|---|---|
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 | |
.
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.
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.
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
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
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:
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 you should use jdbc driver version 7.3 or later
Additional information repositories:
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 There is a service pack available for SQL Server 2000 JDBC driver, release 1/2003.
Points of interest for Microsoft's database server solution:
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: 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:
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 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 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 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:
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
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