
Necessary Products
------------------
A JSDK 2.0 and higher servlet engine.

Special notes:

Apache JServ: Version 1.1 final or higher is required. 
              Previous versions will not work.


Necessary Packages
------------------

Jyve depends on a few libraries in order for it to work. I understand 
that it is a pain to download and install all of these packages and 
I hope to eventually make a distribution tarball of Jyve that includes
everything you need to get started.

Turbine, ECS, Village, JavaMail, Activation, JSDK, Database Drivers

You will need the latest CVS version of Turbine:
    <http://java.apache.org/turbine/>

    Daily CVS snapshots are available from here:
    <http://www.working-dogs.com/daily/>

    Please note that Turbine is still in development, it is required that 
    you get the latest version of Turbine from CVS in order to use Jyve. 
    Work is being done to make final versions of Turbine in order to make 
    Jyve installation easier. Once that work is complete, this document 
    will be updated to reflect the released version of Turbine.

You will need the 1.2 or later version of ECS:
    <http://java.apache.org/ecs/>

You will need Village 1.1 or later:
    <http://www.working-dogs.com/village/>

JavaMail and Activation (latest versions):
    <http://java.sun.com/products/javamail/>

JSDK 2.0 (for use with Apache JServ 1.x) or higher
    <http://java.sun.com/products/servlets/download.html>

(JDBC Database Drivers)

MM MySQL JDBC Drivers (if you use MySQL as your database)
    <http://www.worldserver.com/mm.mysql/>

Oracle JDBC Drivers (if you use Oracle as your database)
    *Note, you need to register to access this URL. It is free.*
    <http://technet.oracle.com/software/tech/java/sqlj_jdbc/software_index.htm>


To Compile
----------

For Win32:
    In the "build" directory is a script called "build-jyve.bat". Edit this 
    script and specify the locations of all the necessary packages outlined 
    above. After you have done this, you can double click this file and it 
    will build Jyve into the "bin" directory.

For Unix:
    In the "build" directory is a script called "build-jyve.sh". Edit this 
    script and specify the locations of all the necessary packages outlined 
    above. After you have done this, you should cd into the build directory 
    and execute the script by typing "sh ./build-jyve.sh".

Executing the above script will create a "bin" directory within the Jyve 
distribution directory. In there will be the compiled class files (inside a 
"classes" directory) as well as a "jyve.jar" file. You can either use the .jar 
file directly or copy the org directory into your classpath ( see below for more 
information on installation ).

If you get compiler error about not being able to find some package, then it 
means that you have not edited the scripts to properly specify the paths to each 
of the packages.



To Install Jyve under Apache JServ
----------------------------------

Place the JavaMail, ECS, Village and Activation .jar files into your 
wrapper.classpath= path in your jserv.properties file.

Place the Turbine and Jyve classes into your repositories= path in your 
zone.properties file.

Please note that the above is just a guideline suggestion. For the reasoning 
please see this FAQ entry URL (which is line wrapped):

<http://java.apache.org/jyve-faq/Turbine/screen/DisplayQuestionAnswer/action
/SetAll/project_id/1/faq_id/2/topic_id/69/question_id/322>

Add the following to your zone.properties file:
    
servlet.Turbine.initArgs=properties=/path/to/TurbineResources.properties

See below for additional generic configuration instructions.



To Install Jyve under Apache Tomcat
-----------------------------------

To use Jyve under Tomcat, you need to set up a webapp directory for
Jyve.  Probably the easiest way to do that is to go to the
turbine/build directory and run "build-turbine war-webmacro".  That
will create the necessary directory structure, with all the necessary
files, in turbine/turbine-war-webmacro.  You should then copy the
entire turbine-war-webmacro directory to $TOMCAT_HOME/webapps/jyve.

Alternatively, you may build the following directory structure by
hand.  It should be placed in your $TOMCAT_HOME/webapps directory.

    jyve
    |-- WEB-INF
    |   |-- classes
    |   |-- conf
    |   |-- lib
    |   `-- templates
    |       |-- layouts
    |       |-- navigations
    |       `-- screens
    `-- images

The following JAR files need to be in one of three places: 1) in your
classpath when you start Tomcat, 2) in $TOMCAT_HOME/lib, or 3) in
$TOMCAT_HOME/webapps/jyve/WEB-INF/lib

    Activation, ECS, JavaMail, Village, an appropriate JDBC Driver
    (such as MM MySQL), and of course Turbine, and Jyve.

If you used Turbine's build program to generate the
turbine-war-webmacro directory, the required JARs (with the exception
of Jyve and an appropriate JDBC driver) will already be in the
WEB-INF/lib directory.  Copy the jyve.jar file to WEB-INF/lib now.

If you built the directory tree by hand, you will need to copy all the
required JAR files to WEB-INF/lib.

If you built the jyve/WEB-INF directory by hand, you will also need to
copy the default TurbineResources.properties from the Turbine
distribution to WEB-INF/conf, and you will need to place the following
in WEB-INF/web.xml:

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

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

<web-app>
  <servlet>
    <servlet-name>Turbine</servlet-name>
    <servlet-class>org.apache.turbine.Turbine</servlet-class>
    <init-param>
      <param-name>properties</param-name>
      <param-value>/WEB-INF/conf/TurbineResources.properties</param-value>
    </init-param>
  </servlet> 
</web-app>


That is it for the Tomcat-specific configuration.  See below for
additional generic configuration.



To Install Jyve under a servlet engine other than JServ or Tomcat
-----------------------------------------------------------------

Place the JavaMail, ECS, Village and Activation .jar files into your
servlet engine classpath.

Plase the Turbine and Jyve classes (or .jar files) into your servlet
engines servlet path (where you would normally place your servlets).

Copy the TurbineResources.properties file from the Turbine
distribution to an appropriate location on your system.

Configure your servlet engine to pass an initial parameter to the
Turbine servlet named "preperties", with the full path to your
TurbineResources.properties file.

Follow the instructions below for additional generic configuration.



Additional Generic Configuration
--------------------------------

Edit your TurbineResources.properties file (that you got from the Turbine 
distribution) and set/change/add the properties below. Please note that you
will need to left align the property names (no space on the left side):

SET:
    mail.server 
    (to be your mail.server that you can relay email through, usually 
    mail.server=localhost is enough)

CHANGE:

    module.packages=
    TO
    module.packages=org.apache.jyve

    screen.homepage=Login
    TO
    screen.homepage=MainMenu
    
    action.login=LoginUser
    TO
    action.login=JLoginUser

    layout.default=WebMacroSiteLayout
    TO
    layout.default=DefaultLayout

    page.default=WebMacroSitePage
    TO
    page.default=DefaultPage

    If you are using MySQL, then set these values appropriately:

    database.default.driver=org.gjt.mm.mysql.Driver
    database.default.url=jdbc:mysql://localhost/jyve
    database.default.username=
    database.default.password=

    locale.default.bundle=MyBundle
    TO
    locale.default.bundle=org.apache.jyve.localization.JyveLocalization

ADD:
    # Set the values below to be appropriate values for your environment:
    jyve.confirm.email.from=nobody@validdomain.com
    jyve.confirm.email.name=Jyve Confirmation
    jyve.confirm.email.subject=Jyve - New Account Confirmation
    jyve.images.root=/path/to/images/root/
    
    # You can modify the following color values according your personal taste:
    jyve.display.color.row.unreleased=FFFF00
    jyve.display.color.table.background=CCCCCC
    jyve.display.color.row.title=006666
    jyve.display.color.row.unreleased.question=FF8800

    jyve.topbar.color.cell.bg.title=006666
    jyve.topbar.htmlcolor.cell.text.title=white
    jyve.topbar.color.cell.bg.value=CCCCCC
    jyve.topbar.htmlcolor.cell.text.value=black

    # You can modify the following options according your personal taste:
    # Those affect the appearance in the DisplayQuestionAnswer screen.
    jyve.displayqa.showcreator=yes
    jyve.displayqa.showlastmodifieddate=yes
    jyve.displayqa.showprevnextnav=yes

    
Next install the database and database schema. The first schema 
(MySQL_users_roles_permissions.sql) is located in the Turbine distribution. The 
second schema (tables.schema) is located in the Jyve distribution. Both are in 
their respective "docs" directories. 
    
    mysqladmin create jyve
    mysql jyve < MySQL_users_roles_permissions.sql
    mysql jyve < tables.schema

For setting the access rights there are two alternative ways (A or B). 
 A: The hacker's way:
    Edit the default MySQL insert script 'Generated_MySQL_Schema.sql'.
    Most important is to set your own passwords. Replace the string
    'changeit!' by any password you like . Furthermore you could
    change the roles - permissions assignments as you wish. Afterwards
    run:

    mysql -f jyve < Generated_MySQL_Schema.sql
   
 B: The more comfortable way which is generating the Generated_MySQL_Schema.sql
    yourself by first editing 'jyve_permissions_roles', 'jyve_users_roles' and
    'header_jyve_access_rights'. You can then run the GenerateRights.[sh | bat]
    script to generate the Generated_MySQL_Schema.sql file.
 
    After doing the generation, have a look at this new file. If everything 
    looks fine, run:

    mysql -f jyve < Generated_MySQL_Schema.sql

    The benefit of doing things is way is that you can keep the primary user 
    accounts and the permissions outside of the database for easy editing. It 
    gets a bit more tricky when you want to re-create the existing Visitor 
    accounts because you must first remove them in order to not get SQL 
    duplicate  insert errors.
    
Lastly, to execute, go to this URL:
    
    http://www.server.com/zone/Turbine
    
    Where www.server.com is your server.
    Where zone == your zone that you put Turbine into.
    
If you are having problems, please subscribe to the Jyve mailing list at 
<http://java.apache.org/main/mail.html>. Include a complete description of the 
problems you are having as well as an log file output and configuration 
settings.
