iEat/defs/docs/release

=======================================================================
iEat - the Internet recipe database
Version @VERSION@ @BUILD_DATE@
=======================================================================

This is the binary distribution of iEat. iEat requires a Java 5
runtime environment, a relational database, and a J2EE application
server to run. Open source software exists for all of these
components. iEat is developed using the Sun Java 5 JDK, the PostgreSQL
relational database, and the Apache Tomcat J2EE application server. The
MySQL relational database is another popular product, and iEat is also
tested against it. See the following URLs for information on these
products:

- Java: http://java.sun.com/
- PostgreSQL: http://www.postgresql.org/
- MySQL: http://www.mysql.com/
- Tomcat: http://tomcat.apache.org/


UPGRADE FROM iEat 1.0 =================================================

The database schema has changed significantly in this release from
the 1.0 release. You will not be able to run the @VERSION@ version of
iEat against the 1.0 database. Look for a SQL script named
"upgrade-1.0-1.2.sql" in the setup/sql/ directory included in
this distribution that will upgrade a 1.0 database to the new format,
preserving your data. Run this script as your exisitng iEat database
user.

Note that not all database types have upgrade scripts yet!


FIRST-TIME DATABASE CREATION ==========================================

First, you must copy the common libraries to the appropriate
directory.

$ cp lib/javamail/*.jar $CATALINA_HOME/lib

You must initialize your database for first-time use. Currently
PostgreSQL 7.x or later and MySQL 4.1 or later are directly
supported:

POSTGRES ------------------------------------------------------------

1) Create a database user for iEat

As a Postgres super-user, execute:

$ createuser -ADEP ieat

You will be prompted to enter the ieat user's password. If you
get a permissions error when you attempt to run this command,
make sure you are executing it as a Postgres user with sufficient
privileges. You can explicity run as the Postgres super-user with

$ createuser -U postgres -ADEP ieat

in which you may be prompted for the postgres user's password.

2) Create a database for iEat

As a Postgres super-user, execute:

$ createdb -E UNICODE -O ieat ieat

Again, you may need to pass the -U flag to specify a Postgres
super-user account to execute the command as. The database
must be created with the Unicode encoding!

3) Copy drivers into common directory

$ cp lib/jdbc/postgresql-8.3-603.jdbc3.jar $CATALINA_HOME/lib

MYSQL ---------------------------------------------------------------

1) Create a database for iEat

As a MySQL super-user, execute the following in the MySQL shell,
i.e. enter 'mysql -u root mysql' to enter the MySQL shell as the
'root' user:

mysql> create database ieat character set utf8;

2) Grant privileges for an iEat database user

Still in the MySQL shell, execute:

mysql> grant all privileges on ieat.* to ieat identified by 'ieat';

Here the "identified by 'ieat'" creates the user's password, which
you should set to whatever you please. Note this allows the
database user 'ieat' to connect to the 'ieat' database from any
host. If you plan on running the iEat application on the same
machine as MySLQ is running on, you could limit the ieat user
to connect only from the local machine with

mysql> grant all privileges on ieat.* to 'ieat'@'localhost'
-> identified by 'ieat';

3) Flush the privileges

To make sure MySQL is ready to be used with the new ieat user,
execute the following (still in the MySQL shell):

mysql> flush privileges;

4) Copy drivers into common directory

$ cp lib/jdbc/mysql-connector-java-5.1.7-bin.jar $CATALINA_HOME/lib

FIRST-TIME DATABASE SETUP =============================================

After creating the database for the first time, you must run
several SQL scripts to create the iEat database tables.

POSTGRES ------------------------------------------------------------

Execute:

$ psql -U ieat -f setup/sql/postgres/setup.sql ieat

Ignore any warnings about "table X does not exist". Then repeat
the above command for the following SQL scripts (substitue
these paths for the -f argument):

- setup/sql/postgres/create.sql
- setup/sql/postgres/load.sql
- setup/sql/postgres/load-ingredients.sql



MYSQL ---------------------------------------------------------------

Execute:

$ mysql -f -u ieat -p ieat
Enter the ieat user password if prompted. Ignore warnings about
tables that don't exist Then repeat the above command for the
following SQL scripts (substitute these paths for the
'setup/sql/mysql/setup.sql' above):

- setup/sql/mysql/create.sql
- setup/sql/mysql/load.sql
- setup/sql/mysql/load-ingredients.sql


FIRST-TIME APPLICATION SERVER SETUP ===================================

iEat depends on the application server it is running in to provide a
JDBC DataSource to connect to the database with and a JavaMail
Session to send emails with. Thus you must configure the deployment
descriptor for iEat the first time you install iEat.

For Tomcat 5.5 or later, create a file located at

/etc/tomcat8/Catalina/localhost/ieat.xml

The structure of this file should look like this:

docBase="/path/to/ieat-1.0.0.war">
type="javax.sql.DataSource" scope="Shareable"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost:5432/ieat"
username="ieat" maxWait="5000" validationQuery="select 1"
password="ieat"
maxActive="5" maxIdle="2" removeAbandoned="true"
removeAbandonedTimeout="60" logAbandoned="true"
/>
auth="Container"
type="javax.mail.Session"
mail.smtp.host="localhost"
/>


The docBase attribute should point to the absolute path of the
iEat WAR included in this package. Then customize the DataSource
and Session definitions to match your environment. For example,
if you plan to use MySQL instead of PostgreSQL, your DataSource
configuration should look more like this:

type="javax.sql.DataSource" scope="Shareable"
driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/ieat"
username="ieat" password="ieat" maxWait="5000"
maxActive="5" maxIdle="2" removeAbandoned="true"
removeAbandonedTimeout="60" logAbandoned="true"
/>


JDBC DRIVERS AND JAVAMAIL =============================================

Your J2EE application server will need access to the JDBC driver for
the database you are using. Drivers for PostgreSQL and MySQL are
provided in the setup/lib directory of this package. Copy the
appropriate JAR file into the appropriate library directory of your
application server. For Tomcat this is /common/lib.

In addition your application server must make the Java Mail API
available to iEat. If it does not have this (by default Tomcat 5
does NOT provide this) you can copy the activation.jar and mail.jar
files from the setup/lib/javamail directory into the appropriate
directory for your application server. For Tomcat this is
/common/lib.


APPLICATION SETUP =====================================================

To install, copy the WAR file included in this package to the path
you specified in your application server config (e.g. the "docBase"
attribute from the deployment descriptor).

Finally, you might want to adjust the application logging, which
by default will attempt to log via Log4J to /var/tmp/ieat.log. You
can adjust the verbosity and location of this log by unpacking the
WAR and editing the /WEB-INF/classes/log4j.properties
Log4J configuration. Then either change your application server
configuration to point to the unpacked WAR directory or zip up the
unpacked WAR directory back to the original file name.

** Note to MySQL users: you must perform an additional step, to
replace the /WEB-INF/classes/ieat.hbm.xml with
the setup/sql/mysql/ieat.hbm.xml version, which has MySQL
implementations of the iEat SQL queries.


FIRST-TIME USE ========================================================

Start up your application server. Once started, visit

http://:/ieat

where is the machine iEat is running on (i.e.
localhost) and is the port the applicaiton server is
listening on (i.e. for Tomcat this defaults to 8080).

You should see the iEat Setup Wizard page. The Setup Wizard will
guide you through configuring the remaining iEat optinos as well as
create your first admin-level user account.


EXSLT/Xerces SUPPORT =================================================

iEat requires a JAXP transformer that includes EXSLT support. Xalan
supports EXLST. You may experience problems using the JAXP parser
supplied with your JDK, however. To get around this, you can use
Xalan and Xerces in place of your JDK's JAXP implementation. To do
this, place the Xalan and Xerces JAR files (available in the
setup/lib/xalan directory) in your app server's "endorsed"
classpath. For Tomcat this means placing these JARs in the
/common/endorsed directory.


=======================================================================
Happy eating!