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 *.jar file can be found on pe2_webapp folder:

  pe2_webapp/target/packeis2.war


==============================================================================
3. DB & Configuration:
3.1 DB
Execute the sql scripts to setup the packeis2 database. The scripts are
'./pe2_databasehandler/src/main/resources/sql-scripts/base-schema.sql' and
'./pe2_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
application. 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:
4.1 Standalone
Create a folder at the desired location and unpack the archive packeis2.zip
to this folder. Now go into that folder and execute the following command:

  java -jar packeis2-<version>.jar


4.2 On Eclipse
On Eclipse you can just run JettyServerMain as an application. There is a
launch configuration for this includet. Just open the pulldown menu
"Run Configurations..." and choose "Run_Packeis2__JettyServerMain" on the
section "Java application".


The webserver is listening on port 8080, so the webapp can be accessed via
the following url:

  http://localhost:8080/


==============================================================================
5. Debug webapp:
As the application can be started directly on Eclipse, just run it in debug
mode and go ahead with debugging :-)

To start debugging real remote, the app has to be started 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-<version>.jar


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


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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - -                  This part is not finished yet                    - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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/