Cofax logo www.cofax.org


Welcome to the Cofax.org web site 
AboutTechnologyDownloadCofax in ActionContactsDevelopmentDocumentationSite map
> Home > Documentation > Installation Instructions /
 
 
   
 

Installation Instructions



For the purposes of this document we will assume you are using a Windows operating system (2000, NT, 98, 95), Jakarta Tomcat, and MS SQL Server. If you are using other products the details of the installation will change, but the basic process remains the same.

Note that if you plan to compile and develop Cofax source, please read Cofax Developer Environment first.



 
 

> Install CDS and CMS web applications


  • Stop the Tomcat Server in case it is running right now. Issue a $TOMCAT_HOME/bin/shutdown.bat command.
  • Download content.war from the download page of this site to $TOMCAT_HOME/webapps.
  • Start Tomcat back up by running $TOMCAT_HOME/bin/startup.bat. Go to URL http://localhost:8080/content. This will expand the content.war into the $TOMCAT_HOME/webapps/content directory. You will see a a page, but the system is not fully operational yet.
  • Stop Tomcat again so that we can configure Cofax. Run the $TOMCAT_HOME/bin/shutdown.bat command.


  •  
     

    > Requirements for all layers of the archetecture


  • Tomcat or other servlet container to run the CDS and CMS for Cofax. These instructions are Tomcat specific, your mileage may very.
  • If Tomcat is installed to d:\usr\local\tomcat installation is greatly simplified.
  • Your servlet container(Tomcat) should already be operational. For Tomcat you must get to the point where you can run the examples from the default install at http://localhost:8080/
  • You need the JRE or JDK version 1.3 or higher installed.
  • You will need MS SQL Server to store your content. Note that you can change this default behavior by overriding the org.cofax.DataStore class.
  • If you have created a server alias called LOCALHOST using the SQL Server Client Network utility, installation is greatly simplified.
  • You will need a JDBC database driver installed. Microsoft provides a free JDBC driver at http://www.microsoft.com/sql/downloads/2000/jdbc.asp This particular driver will make installation easier since the default configuration in the downloads use this.
  • Prepare yourself and your servers. Make sure you know where you want to install Cofax, and you have all the machines ready to go, you have the right set of access to the file system and you have pleanty of free space to work with. Cofax itself is very small but its always better to have lots of room to grow.


  •  
     

    > Definitions used in this document


  • CDS = Content Display System
  • CMS = Content Management System
  • CDW = Content Data Warehouse
  • $TOMCAT_HOME = directory where Tomcat is installed.


  •  
     

    > Installing the MySQL CDW


  • Drivers are already provided for MySQL.
  • Extract cdw_mysql.zip to a temporary directory. This file is included with the distribution. If you are a developer, the contents of this zip are located at $PROJECT_HOME/apps/cdw_mysql.
  • Windows users MUST create a file named c:\my.cnf with these contents:
    [mysqld]
    set-variable= lower_case_table_names=0
  • cd to the directory you extracted the zip file.
  • Run:
    >mysql -u [adminuser] -p
    >password: *****
    mysql> create database goon;
    mysql> use goon;
    mysql> source goon.sql
    mysql> quit 
  • Edit the Cofax config file for database access. $TOMCAT_HOME/webapps/content/WEB-INF/web.xml. If you are a developer, instead edit $PROJECT_HOME/apps/content/WEB-INF/web.xml and run ant.
  • Start Tomcat. Run the $TOMCAT_HOME/bin/startup.bat command.


  •  
     

    > Using Cofax


  • Browse to http://localhost:8080/content/main.htm to see the CDS welcome screen.
  • Browse to http://localhost:8080/content/tools/ and see the CMS toolset. Signon as admin. Password admin. Sample data exists for publication "Heartland Crier" for 03/01/2002.
  • Sample templates for "Heartland Crier" are at the template root $TOMCAT_HOME/webapps/content/templates/.
  • Sample static data (images, etc) for "Heartland Crier" are at $TOMCAT_HOME/webapps/content/static/heartland_crier.
  • At this point you are fully functional except for three non-neccessary but desireable functions (DOCS TO BE ADDED):
    • Image Management (TO BE ADDED)
    • Behind firewall Template Management (TO BE ADDED)
    • Feed (TO BE ADDED)


  •  
     

    > Installing the MS SQL Server CDW


  • Install MS SQL Server drivers (note they are not performance tested) from this address.
  • Copy the MS SQL Server JDBC jar files, located in the lib directory where you installed the drivers, to $TOMCAT_HOME/webapps/content/WEB-INF/lib.
  • Extract cdw_ms.zip to a temporary directory. This file is included with the distribution. If you are a developer, the contents of this zip are located at $PROJECT_HOME/apps/cdw_ms.
  • Create a new database in SQL Server called "goon" (don't ask).
  • Run the goon.sql file included in cdw_ms.zip while using the goon database. You can do so either by:
    • Connecting to your server with Query Analyzer and opening the file.
    • Or by running a command line isql command using the file: isql -i goon.sql. Note, you must execute this command while the command prompt is in the same directory as the goon.sql file.
  • Import your startup data by opening Enterprise Manager for SQL Server, choosing the goon database, right clicking, choosing 'All Tasks', choosing Import Data. Pick Microsoft Access from the Source drop down. Use the ellipsis (...) button to locate the Access database named populateGoon.mdb you extracted from cdw.zip. Click Next. Choose the server you created the goon database on, type in your username/password, choose the goon database. Click Next. Choose 'Copy Table(s)' from the options presented and click Next. Click Select All. Click Next. Keep the default 'Run Immediately'. Click Next.
  • If you have a SQL Server alias called LOCALHOST (see above), are using sa and blank password for testing, have installed Tomcat to d:\usr\local\tomcat, skip next step.
  • Edit the Cofax config file for database access. $TOMCAT_HOME/webapps/content/WEB-INF/web.xml. If you are a developer, instead edit $PROJECT_HOME/apps/content/WEB-INF/web.xml and run ant.
  • Start Tomcat. Run the $TOMCAT_HOME/bin/startup.bat command.


  •  
     

    > Securing Your Cofax Installation


  • This sounds like common sense but it needs to be said - Never use sa or blank passwords to access database. Change port of database. Edit $TOMCAT_HOME/webapps/content/WEB-INF/web.xml to change database connectivity parameters.
  • Never leave CDS Admin cache administration at default URL. Edit $TOMCAT_HOME/webapps/content/WEB-INF/web.xml and change servlet-mapping for cofaxAdmin, removePageCache, and removeTemplateCache init-params to appropriate values. Obfuscate these URLs.
  • While Editor's Tools do provide basic security - KRD does not run Editor's Tools on outside firewall machines. You will need multiple machines to accomplish this. Edit $TOMCAT_HOME/webapps/content/WEB-INF/web.xml and remove the cofaxTools servlet config from the display machine. When doing this, you can now take advantage of SQL Server security by having the Editor's Tools machine be configured with a SQL Server user that has rights to run "s_" prefixed stored procedures and a Display machine user that does not. This will effectively lock down your database server from malicious intent. Do not give Display user direct rights to any database tables or views. Stored procedures are all that are required for db access in Cofax.
  • Move serving static resources (images, etc) from Cofax in Tomcat to Apache. Doing so reduces the need for access to the CDS file system. Edit $TOMCAT_HOME/webapps/content/WEB-INF/web.xml init-param configGlossary:staticPath and point to the new relative URL and there is no need to change any templates.

    More notes to come



  •  
     

    > Recommendations for Hosting Cofax for High Scalability


    Out of the box, Cofax provides a highly tunable cache to provide scalability for most low traffic sites. Follow the recommendations below to achieve the scalability required for sites like the Philadelphia Inquirer. Below I will describe a series of levels to use to scale up for varring degrees of performance requirements.
  • Level 0 - Tune Tomcat, JVM, and database, to use memory efficiently. Tune cache parameters in $TOMCAT_HOME/webapps/content/WEB-INF/web.xml to cache as many pages and templates as memory allows. Note, typically the templates and packageTag caches can be tuned to low figures (under 200 to track and cache), since the db contains fewer then 200 packageTags and even the Philadelphia Inquirer, the most complicated Cofax site yet launched, utilized less then 100 templates. Most sites get by with 4 to 8 templates.
  • Level 1 - Seperate the layers vertically . Follow the recommendation above to host the Editor's Tools (CMS) on a seperate machine. Host the database on a seperate machine. Install Apache on an additional machine. Move static resources from Cofax to be served by Apache directly. Edit $TOMCAT_HOME/webapps/content/WEB-INF/web.xml and edit init-param configGlossary:staticPath so templates will access images and other static data from this new relative URL path.
    • Cofax Page: UserBrowser->ApacheServer->CDSTomcatServer->Database1
    • Static Resources: UserBrowser->ApacheServer
    • Content Management: EditorBrowser->CMSTomcatServer->Database1
  • Level 2 - Seperate the layers horizontally.

    More notes to come.



  •  
       

    Powered by Cofax - Please see www.cofax.org for more information.

    Valid HTML 4.01!    Valid CSS!