<?xml version="1.0" encoding="iso-8859-1"?>

  <chapter>
    <title>Installation
    <sect1 id="install_system">
      <title>System requirements
      <para>
        mvnForum has the following system requirements:
        <itemizedlist>
         <listitem>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.</para>
         <listitem>JDK 1.3 or later
         <listitem>A JDBC 2.0-compliant database (see  for list of supported databases
          (this release includes 4 drivers: mm.mysql, Connector/J, postgreSQL and hsqldb)</para>
        </itemizedlist>
      </para>
    </sect1>
    <sect1>
      <title>Application Server
       <para>
         Follow these steps to setup the application server.
         <itemizedlist>
          <listitem>Create a home folder for mvnForum, which MUST NOT be accessible from the web.
            This mvnForumHome folder is <emphasis>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.</para>
          <listitem>Unzip the distributed zip file into this folder.
          <listitem>Create a context in your app server.  See the application server-specific configuration options for your server.
          <listitem>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>Set database parameters to the correct values.  Database server-specific information is presented  and also in
              the header of the sql script file.</para>
            <note>Currently you have to restart your App Server if you make changes
              in properties files (if not, your new config cannot take effect)</para>
          <listitem>Copy the content of webapp dir in the extracted folder to the context dir that you have created above.
          <listitem>If you dont need some language support, just delete the folder for that language
              <informalexample>Ex: If you dont need Vietnamese support (locale is vi), delete the folder for that language
               <filename class="directory">webapp/mvnplugin/mvnforum/user/vi
          </listitem>
          <listitem>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
              <informalexample>Ex: to change the default language from English to Vietnamese (locale is vi), just copy
                  all files from <filename class="directory">webapp/mvnplugin/mvnforum/user/vi to
                  <filename class="directory">webapp/mvnplugin/mvnforum/user
           </listitem>
         </itemizedlist>
       </para>
      <sect2>
        <title>Apache Tomcat Application Server
        <para>
           Following is tomcat-specific application server setup configuration information:
           <itemizedlist>
             <listitem>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.</para>
             <listitem>For additional information on Tomcat contexts,
             visit the <ulink url="http://jakarta.apache.org/tomcat/tomcat-4.0-doc/config/context.html">Apache Tomcat site
             </para>
           </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>Caucho Resin Application Server
        <para>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):
           <itemizedlist>
             <listitem><resin-root>/mvnplugin
             <listitem><resin-root>/mvnplugin/mvnforum (contains all JSP files)
             <listitem><resin-root>/mvnplugin/WEB-INF (created by RESIN)
             <listitem><resin-root>/WEB-INF/
             <listitem><resin-root>/WEB-INF/web.xml (see below)
             <listitem><resin-root>/WEB-INF/listitemb/
             <listitem><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)
             <listitem><resin-root>/WEB-INF/classes/
             <listitem><resin-root>/WEB-INF/classes/*.properties files (7 files)
           </itemizedlist>
           Snippet of web.xml:
            <literallayout>
            <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>
          </literallayout>
          This results in an application that maps to:
             http://<host name>/brds/index
        </para>
      </sect2>
      <sect2>
        <title>Weblogic Application Server
        <para>
           Following are notes on installing/configuring mvnForum in a WebLogic 7.0 context:
           <itemizedlist>
             <listitem>Copy the files from the webapps folder that came with mvnForum distribution into
                the weblogic applications directory and deploy it using the WLS console.</para>
             <listitem>Setup the database (MySql as an example) by creating a connection pool with these parameters
                <itemizedlist>
                  <listitem>name: mySQLConnectionPool
                  <listitem>URL: jdbc:mysql://localhost/mvnforum
                  <listitem>driver: org.gjt.mm.mysql.Driver
                  <listitem>properties: user=mvnforum
                  <listitem> password=mvnforum
                  <listitem>number of connections:  10 (your choice here)
                </itemizedlist>
             </para>
             <listitem>Create a datasource for this pool
                <itemizedlist>
                  <listitem>name: mySQLDataSource
                  <listitem>JNDI Name: mySQLDataSource
                  <listitem>Pool Name: mySQLConnectionPool
                </itemizedlist>
             </para>
             <listitem>Do not forget to add the driver in the server classpath.
             <listitem>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).</para>
             <listitem>In mvncore_db_DBOptions.properties, comment out all entries but
               USE_DATASOURCE = true and DATASOURCE_NAME=mySQLDataSource.</para>
           </itemizedlist>
           <note>The only change noted to upgrade from WLS 7 to 8 is to change the ACL from mySQLConnectionPool
               to weblogic.jdbc.connectionPool.mySQLConnectionPool</para>
        </para>
      </sect2>
      <sect2>
        <title>Other...
      </sect2>
    </sect1>
    <sect1 id="databases">
      <title>Database Server
      <sect2>
        <title>First-Time Database Installation
          <para>
            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.</para>
            <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</para>
            <itemizedlist>
                <listitem>In the extracted folder, find the file sql/mvnForum_<supported database server>.sql
                <listitem>Create a database and confirm the correct database parameters have been set in the application server configuration step
                <listitem>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.
                <listitem>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)</para>
            </itemizedlist>
            <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
            <filename>mvncore_db_DBOptions.properties. This is the quickest way to get started with mvnForum.
           </para>
      </sect2>
      <sect2>
        <title>Database Upgrades
        <para>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 <emphasis>highly recommemd
          that you back up all your data.
        </para>
        <sect3>
          <title>General Upgrade Notes
            <para>To upgrade from beta1, beta2, beta3 or rc1 release, READ THE FOLLOWING NOTES CAREFULLY
            <para>
              <itemizedlist>
                <listitem>Update the sql script first, please look at mvnforum\sql\upgrade
                <listitem>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)
                <listitem>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)
                <listitem>Delete your current servlet context of mvnForum before continueing the setup
                <listitem>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)
                <listitem>After setting up successfully, restore the avartars that you have backuped above
                <listitem>Run and test if mvnForum can run properly, and confirm the mvnForumHome has been configured properly
                <listitem>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
              </itemizedlist>
              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.
            </para>
        </sect3>
        <sect3>
          <title>Beta1/Beta2 to Beta3
          <para>The database from the beta1 and beta2 schema changed on the upgrade to beta3:
            <itemizedlist>
              <listitem>Updated database schema - mvnformForum table's unique index
                changed from ForumName to ForumName and CategoryID</para>
            </itemizedlist>
          </para>
          <para>Use this script to upgrade to beta 3 (for mySQL and other databases that support this):
             <filename>sql\upgrade\1_0_0_beta2_to_1_0_0_beta3\mvnForum_update_mysql.sql.
                Modify this file to suit your database requirements
           </para>
         </sect3>
         <sect3>
           <title>Beta3 to Release Candidate 1
           <para>The database from the beta3 schema changed on the upgrade to RC1:
             <itemizedlist>
               <listitem>Added two tables to the schema: mvnforumWatch and
                  mvnforumAttachment</para>
             </itemizedlist>
           </para>
           <para>Use this script to upgrade from beta 3 to rc1 (find scripts for each supported database server):
              <filename>sql\upgrade\1_0_0_beta3_to_1_0_0_rc1\mvnForum_update_mysql.sql.
                Modify this file to suit your database requirements
            </para>
         </sect3>
      </sect2>
      <sect2>
        <title>MySQL
        <para>
          Some key points to using MySQL as the database for persisting forum threads
          <itemizedlist>
            <listitem>Driver: com.mysql.jdbc.Driver or org.gjt.mm.mysql.Driver
            <listitem>Url: jdbc:mysql://localhost/<database server>?useUnicode=true&characterEncoding=utf-8
            <listitem>Additional resources:
              <itemizedlist>
                <listitem>MySQL dot Com
                <listitem>O'Reilly on MySQL
              </itemizedlist>
             </para>
            </listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>postgreSQL
        <para>
          Some interesting tidbits about storing the forum discussions in the postgreSQL database
          <itemizedlist>
            <listitem>Driver: org.postgresql.Driver
            <listitem>Url: jdbc:postgresql://<database host name>:<host port>/<database name>
              <note>you should use jdbc driver version 7.3 or later
            </para>
            <listitem>Additional information repositories:
              <itemizedlist>
                <listitem>postgreSQL dot org
                <listitem>JDBC drivers for posgreSQL
              </itemizedlist>
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>Microsoft SQL Server
        <para>
          Some commercial notes about a commercial product
          <itemizedlist>
            <listitem>Driver: com.microsoft.jdbc.sqlserver.SQLServerDriver
            <listitem>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.
            </para>
            <listitem>Points of interest for Microsoft's database server solution:
              <itemizedlist>
                <listitem>Home of SQL Server
                <listitem>JDBC drivers for SQL Server
              </itemizedlist>
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>Oracle
        <para>
          Let the wisedom of the oracle guide you with this one
          <itemizedlist>
            <listitem>Driver (both 8 and 9i): oracle.jdbc.driver.OracleDriver
            <listitem>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</para>
            </para>
            <listitem>Links from o to q:
              <itemizedlist>
                <listitem>Oracle's Technical Home
                <listitem>JDBC drivers info for Oracle
                <listitem>Download driver
              </itemizedlist>
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>SAPDB
        <para>
          <blockquote>Aaron HolmesIn 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 (<ulink url="http://www.sapdb.org">www.sapdb.org) and an
          active mailing list (<ulink url="http://www.sapdb.org/sap_db_contact.htm">www.sapdb.org/sap_db_contact.htm).
          <para>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.
            <ulink url="http://www.robelle.com/tips/sapdb.html">From web
            </para>
          </blockquote>
          Don't let the strain sap you of your energy, read on to glean key points on this database
          <itemizedlist>
            <listitem>Driver:  com.sap.dbtech.jdbc.DriverSapDB
            <listitem>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</para>
            </para>
            <listitem>Links from o to q:
              <itemizedlist>
                <listitem>Some SAPDB Information
                <listitem>SAPDB and JDBC
              </itemizedlist>
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>hsqldb
        <para>
          <blockquote>http://hsqldb.sourceforge.net/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.</para>
          </blockquote>
          <itemizedlist>
            <listitem>Driver: org.hsqldb.jdbcDriver
            <listitem>Url: jdbc:hsqldb:<database name>
                      <para>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:</para>
                      <para>DATABASE_URL = jdbc:hsqldb:c:\\mvnForumHome\\hsqldb\\mvnforum
            </listitem>
            <listitem>User: sa
            <listitem>Pasword:
            <listitem>
              <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.</para>
                   <para>Read more on  http://sourceforge.net/forum/forum.php?thread_id=838632&forum_id=73673
            </para>
            <listitem>
              <itemizedlist>
                <title>Links on help with hsqldb:
                <listitem>HSQL Database at SourceForge dot net
              </itemizedlist>
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </sect2>
      <sect2>
        <title>Other...
      </sect2>
    </sect1>

    <sect1>
      <title>Setup Administrator Control panel
      <para>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
      </para>
      <para>
        <itemizedlist>
          <listitem>home for mvnForum - http://www.[yourserver].com/[yourcontext]/mvnforum/index
          <listitem>Administrator Control Panel - http://www.[yourserver].com/[yourcontext]/mvnforumadmin/index
        </itemizedlist>
        <itemizedlist>
          <listitem>home for mvnForum - http://www.[yourserver].com/mvnforum/index
          <listitem>Administrator Control Panel - http://www.[yourserver].com/mvnforumadmin/index
        </itemizedlist>
      </para>
      <para>Go to the Admin Zone and enter username = admin and password = admin
      <para>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)</para>
      <para>The index page you see when you login also give you other info, including
            database and system info</para>
      <para>Go to the Admin Zone and enter username = admin and password = admin
      <para>Change the password and edit your profile by clicking Forum Index -> MyProfile
      <para>Click Forum Management to create categories/forums for your community
      <para>You can create new users and set permissions for these new users
    </sect1>
    <sect1>
      <title>Troubleshooting
      <para>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
        <itemizedlist>
           <title>Basic reminders
           <listitem>Make sure you meet the system requirements
           <listitem>Make sure you have read this installation guide carefully
           <listitem>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
           <link id="dev_build" linkend="dev_build">instructions
           <listitem>Make sure you have read the short database guide in
             <filename>sql/mvnForum_<database>.sql carefully
        </itemizedlist>
        <itemizedlist>
           <title>Error messages
           <listitem>Error executing SQL in MVNForumPermissionWebHelper.getPermissionsForGroupGuest
             <para>
                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:
             </para>
             <para>
                Can't create a new connection in DBConnectionPool. URL = ....
             </para>
             <para>
                You can configure the log4j.properties to log all messages to file and use
                this file to find your database problem
              </para>
           </listitem>
           <listitem>Cannot upload an avatar to the server
             <para>This is most likely an image support problem, please search the
               mvnForum for keyword headless</para>
           <listitem>Error says 'Cannot update table Thread where primary key = (3)
             <para>This is probably a database driver issue.  Some drivers do not properly support
               the JDBC standards needed by mvnForum.  See <ulink url="http://www.mvnforum.com/mvnforum/viewthread?thread=304">
               this thread for more</ulink>
        </itemizedlist>
        Remember, you can now search the mvnForum online to see if someone else has
        dealt with the problem you are facing.
        <itemizedlist>
           <title>If all else fails...gather this information and post a question
           <listitem>Your mvnForum version (such as rc1, build 24 April 2003)
           <listitem>Your OS version (Such as Windows 2000 service pack 2)
           <listitem>Your App Server version (Such as Tomcat 4.1.24)
           <listitem>Your Database version (Such as Mysql 3.23.51)
           <listitem>Your JDBC driver version (Such as mysql-connector-java-3.0.8-stable-bin.jar)
           <listitem>Your mvnForum .properties files content
           <listitem>Any stacktrace that you found
           <listitem>Any other information that you think useful to solve the problem
        </itemizedlist>
      </para>
    </sect1>
    <sect1>
      <title>Versions
    </sect1>
  </chapter>