WPI GDC Club Management System — Installation Instructions

Installing the CMS system is currently faily complicated and involves a bit of work with MySQL, Tomcat and Cocoon.  The first step is to install MySQL, Tomcat, and Cocoon.  Instructions are on their various webpages: MySQL's web page, Tomcat's web page, Cocoon 2's web page.

Cocoon 2 Notes:

1. Under UNIX, Java requires an X server to be running for various Java AWT API calls that Cocoon uses to succeed.  To resolve this issue without running a full X server, try using Xvfb, part of the standard X11R6 package.  That link details the XFree86 X server package, which runs on several platforms, and is the package I use on my server.  Some binary installations do not include Xvfb, so you may need to build it from source.
2. Cocoon 2 contains several SVG classes.  On my machine, the SVG classes would prevent the server from starting.  If Cocoon 2 won't start, then in the <map:serializers> part of the Cocoon 2 sitemap, try removing the following lines:

   <map:serializer name="svgxml" mime-type="image/svg-xml"
     src="org.apache.cocoon.serialization.XMLSerializer">
    <doctype-public>-//W3C//DTD SVG 20000303 Stylable//EN</doctype-public>
    <doctype-system>http://www.w3.org/TR/2000/03/WD-SVG-20000303/</doctype-system>
   </map:serializer>
   <map:serializer name="svg2jpeg" mime-type="image/jpeg"
     src="org.apache.cocoon.serialization.SVGSerializer">
    <!-- example parameter - background colour is bright green
    <parameter name="background_color" type="color" value="#00FF00"/>
    -->
   </map:serializer>
   <map:serializer name="svg2png" mime-type="image/png"
     src="org.apache.cocoon.serialization.SVGSerializer">
   </map:serializer>
   

Test Tomcat and Cocoon 2 before trying to install CMS on top of them.  That way, when you install CMS and Cocoon 2 stops working, you know who to blame.

Once Tomcat and Cocoon 2 are running, you are ready to setup the CMS system.  If building from source, use ant package to create the cms.jar file.  Add this to either your classpath or to the Cocoon 2 lib directory.

Next modify your Cocoon 2 sitemap.  First, add the following lines to the <map:transformers> section:

<map:transformer name="cms" src="org.wpi.gdc.cms.transform.CMSTransformer">
  <config-file>/path/to/cms.conf</config-file>
</map:transformer>

You will need to modify the /path/to/cms.conf to point to whereever you placed your cms.conf file.  After that, add the following lines to the <map:pipeline> section:

<!-- Does HTML processing -->
<map:match pattern="cms/*.html">
  <map:generate src="/path/to/cms/files/{1}.xml"/>
  <map:transform type="cms"/>
  <map:transform type="xslt" src="/path/to/cms/files/cms.xsl"/>
  <map:serialize/>
</map:match>
<!-- Returns the raw XML instead, otherwise is the same as above -->
<map:match pattern="cms/*.xml">
  <map:generate src="/path/to/cms/files/{1}.xml"/>
  <map:transform type="cms"/>
  <map:serialize type="xml"/>
</map:match>
<!-- Allows access to static content -->
<map:match pattern="cms/static/*.css">
  <map:read src="/path/to/static/cms/files/{1}.css" mime-type="text/css"/>
</map:match>
<!-- For debugging: returns the XML "source code" -->
<map:match pattern="cms/*.cms">
  <map:read src="/path/to/cms/files/{1}.xml" mime-type="text/plain"/>
</map:match>

The first two sections are the "main" CMS entries - required for every useful install.  The third is only useful if you are hosting static content in the Cocoon namespace (this is not the best idea).  You will want to remove the last section once you have the server running, since it allows direct access to the XML "source."

Replace the /path/to/cms/files in the above with whereever you placed your CMS XML framework files.

The final step is to modify your CMS configuration file to use your database.  You'll want to change the dburl to point to your database, as well as change the non-existant JDBC engine to org.wpi.gdc.cms.db.jdbc.MySQLDBEngine (in the future, the MySQL engine will be replaced with a generic JDBC engine and the change will not be necessary - right now, only MySQL is supported).  The result should look like the following:

<database
  dbengine="org.wpi.gdc.cms.db.jdbc.MySQLDBEngine"
  dburl="jdbc:mysql://127.0.0.1/cms">
    <param name="user">user</param>
    <param name="password">password</param>
  </database>

Right now, you also need to initialize the MySQL database.  The script to do so is not in the CVS package, as the final version will complete this step for you on the first run.  The SQL script to do so is available here.