iEat/defs/docs/release/README.bin.txt

=======================================================================
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/<db> 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 <setup/sql/mysql/setup.sql
  
  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:
  
  <Context path="/ieat" reloadable="false" 
  		docBase="/path/to/ieat-1.0.0.war">
	<Resource name="jdbc/ieat" 
		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"
	/>
	<Resource name="mail/ieat" 
		auth="Container" 
		type="javax.mail.Session"
		mail.smtp.host="localhost"
	/>
  </Context>
  
  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:
  
	<Resource name="jdbc/ieat" 
		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 <TOMCAT HOME>/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 
  <TOMCAT HOME>/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 <IEAT HOME>/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 <IEAT HOME>/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://<your server>:<port>/ieat
  
  where <your server> is the machine iEat is running on (i.e. 
  localhost) and <port> 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 
  <TOMCAT HOME>/common/endorsed directory.


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