Notes and noteworthy stuff
                    to compile, setup and use PackEis2

  Created: 2009-12-13 starwarsfan
  Version: $Id$


  1. Preparation
  2. Compiling webapp
  3. DB & Configuration
  4. Start webapp
  5. Debug webapp
  6. Usage as service
  A  Links


==============================================================================
1. Preparation
1.1 Maven
The build is done using Apache Maven. To handle different types of archives
packeis2 uses 7zip which currently not available using a maven repository.
Because of this the required files must be installed in your local maven
repository by hand. The repository normally is located in ~/.m2/repository/
(Linux) or %USERPROFILE%/.m2/repository (Windows). To install z7ip files just
unpack project/contenthandler/src/main/lib/net.zip into .m2/repository/

1.2 MySQL
PackEis2 uses MySQL to store package metadata etc. So you need a running and 
accessible MySQL database installation. To setup packeis2 database, see 
section 'DB & Configuration'.


==============================================================================
2. Compiling webapp:
To compile the webapp the following requirements must be satisfied:
- Installed JDK like [1]
- Installed Maven [2]
- Internet access to download required Maven artifacts

Check with the following command if Maven works correct:

  mvn --version

The output must be something like this:

  D:\coding\eisler\eis\trunk\src\pack-eis2\project>mvn --version
  Apache Maven 2.2.1 (r801777; 2009-08-06 21:16:01+0200)
  Java version: 1.6.0_16
  Java home: C:\Program Files (x86)\Java\jdk1.6.0_16\jre
  Default locale: de_CH, platform encoding: Cp1252
  OS name: "windows 7" version: "6.1" arch: "x86" Family: "windows"

To compile the webapp cd into the top level folder (where this document is
located) and use the following command:

  mvn clean install

During first use of this command Maven will download a lot of required
artifacts and store them into %USERPROFILE%\.m2\repository\ respectively
~/.m2/repository/. After the first run Maven just checks for newer versions
if neccessary and uses the stored artifacts.

If compilation is finished the *.war file can be found on webapp folder:

  webapp/target/packeis2.war


==============================================================================
3. DB & Configuration:
3.1 DB
Execute the sql scripts to setup the packeis2 database. The scripts are
'./databasehandler/src/main/resources/sql-scripts/base-schema.sql' and 
'./databasehandler/src/main/resources/sql-scripts/base-data.sql'. A database
'packeis2' will be created.

3.2 Configuration file
Place file 'packeis.properties' on home folder of the user which runs the
webserver. Remove comments of desired key-value-pairs and modify them as
neccessary. Especially the database settings needs to configured with proper 
values to access the database. If database is running on the same machine, 
only org.eisfair.packeis.db.User and org.eisfair.packeis.db.Password needs to
be modified.


==============================================================================
4. Start webapp:
Deploy the *.war file to a servlet container like tomcat. Development and
testing ist done using tomcat6, so it may not work with another major release.




- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - The following parts are currently broken because of strange jetty - - -
- - -     behaviour, so a servlet container like tomcat is required     - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

  java -jar packeis2.war

The components will be extractet to a temporary folder and the webserver is
listening on port 8080, so the webapp can be accessed via the following url:

  http://localhost:8080/packeis2


==============================================================================
5. Debug webapp:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - This part is currently broken because of strange jetty behaviour  - - -
- - -         so a servlet container like tomcat is required            - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

To debug application, it must be startet with debug settings:

  -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044

On Windows do this:
  set DEBUG_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044
  java %DEBUG_OPTS% -jar PackEis2.war

Now the debugger can connect to the running webapp using port 1044.


==============================================================================
6. Usage as service

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - This part is currently broken because of strange jetty behaviour  - - -
- - -         so a servlet container like tomcat is required            - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Based on Tanuki Java Service Wrapper [3] the application can be used as a
service. Sub-project 'trunk/src/pack-eis2/project/service_wrapper' contains
all required components. To do so the following steps must be done:
- Place the content out of src/main/<your-architecture> in /
- Put packeis2.war to /usr/lib/packeis2/bin/
- See available option with this command:

  /usr/lib/packeis2/bin/packeis2 --help

- Start app for instance with

  /usr/lib/packeis2/bin/packeis2 console

TODO if neccessary:
- Create link /etc/init.d/packeis2 --> /usr/lib/packeis2/bin/packeis2
- Create RC-links to init script

==============================================================================
A Links:
[1] http://java.sun.com/javase/downloads/index.jsp
[2] http://maven.apache.org/
[3] http://wrapper.tanukisoftware.org/