XPlanner Installation

WARNING: These instructions are not applicable for 0.7 betas.
Please refer to the README.txt in the top directory of the distribution package for detailed installation instructions.

Basic Requirements

• Ant
• MySQL is the preferred XPlanner relational database. Configure MySQL with transacted tables (InnoDB)! (See also: other databases.)
• JDK 1.4+
• Servlet 2.3 (JSP 1.2) or better compatible container (e.g. Tomcat 4.x )

1. Get the source code

Download the latest release or check out the sources from Subversion.

If you are using Tomcat. Read the Tomcat installation notes. This information includes instructions on importing an existing tomcat-users.xml file. There are also some additional notes for the OC4J application server.

2. Configure the database

XPlanner uses a relational database to store data, so the relational database must be prepared for use by XPlanner.

Set up the JDBC driver:

XPlanner comes with the JDBC drivers for MySQL and HSQLDB. If you want to use a different database (see information about other databases), obtain the JDBC driver jar file for that database and place it in the lib/jdbc-driver directory before building the XPlanner web application. It's a good idea to confirm that the driver/database combination works outside of XPlanner before proceeding further.

If you need extra help configuring MySQL, it's available here.

Configure the properties:

Look in the xplanner.properties file for the set of database connection properties which apply to your database. You will need to edit or override the properties. Even though you can directly change the properties in xplanner.properties it is advised to override these properties in a custom property file named xplanner-custom.properties instead. This will make upgrade simplier since you won't have to figure out what changes you made to the xplanner.properties to re-incorporate them into the new release xplanner.properties. The custom file must be located in the same directory as xplanner.properties

hibernate.dialect=<hibernate dialect>
hibernate.connection.url=<your JDBC url>
hibernate.connection.username=<your database user>
hibernate.connection.password=<your database password>

(The xplanner.properties file has commented examples for MySQL and HSQL. )

Install the schema:

Note: If you have an existing XPlanner 0.4 MySQL database you can upgrade using the version-specific scripts in xplanner/sql. These scripts will also serve as an example for upgrading databases other than MySQL. Be sure to back up your data before attempting to upgrade!

There are two options for installing the database schema, automatic and manual.

Automatic installation is easy, but can potentially destroy existing data (including previous XPlanner installations), so you should use it with extreme caution! This option is only recommended when you are doing a brand new installation in a dedicated XPlanner database. For automatic installation, in the XPlanner root directory run

This target will use the information in the xplanner.properties to create the tables that XPlanner requires. It will also create a user called 'sysadmin' with password 'admin' if one does not already exist. Use this login for initial access to XPlanner and change the password immediately.

For manual installations, run

in the XPlanner root directory. This command will create a file called hibernate_schema.sql in the project build directory. This file will contain all of the DDL commands which XPlanner requires to run against the database specified in the xplanner.properties file. Once this file is created it can be inspected for potential problems, edited, and executed. The details of this process will depend on the local configuration and the particular database being used.

3. Configure email

The XPlanner distributed integration token uses email to notify people waiting to integrate their code. To configure email, set the following properties in xplanner.properties.

xplanner.mail.smtp.host=localhost        # enter your SMTP host
xplanner.mail.from=xplanner@example.org  # enter the email sender for XPlanner messages

4. Build the xplanner.war file

Go to the base XPlanner directory (the one containing build.xml). Run

$ ant build.war

The xplanner.war file will be build in the build directory.

5. (Optional) Configure your JVM for server-side graphic generation

If you are running XPlanner on a Unix-like system and you are having problems with the XPlanner charts it could be cause by not having an X window server running on the server. This can result in an error in the web server log file looking something like...

java.lang.NoClassDefFoundError
    at com.jrefinery.chart.axis.Axis.<init>(Unknown Source)
    at com.jrefinery.chart.axis.CategoryAxis.<init>(Unknown Source)
    at com.jrefinery.chart.axis.HorizontalCategoryAxis.<init>(Unknown Source)
    at com.jrefinery.chart.ChartFactory.createLineChart(Unknown Source)
    at de.laures.cewolf.taglib.CewolfChartFactory.getChartInstance(CewolfChartFactory.java:79)
    at de.laures.cewolf.taglib.ChartDefinitionImpl.getChart(ChartDefinitionImpl.java:89)
    at de.laures.cewolf.taglib.ChartImageDefinitionImpl.getChart(ChartImageDefinitionImpl.java:99)
    at de.laures.cewolf.util.Renderer.renderChart(Renderer.java:97)
    at de.laures.cewolf.util.Renderer.render(Renderer.java:83)
    at de.laures.cewolf.taglib.ChartImageDefinitionImpl.ensureRendered(ChartImageDefinitionImpl.java
    ...

There are several solutions to this problem. You can run an X server on the XPlanner host. Often this is not desirable if the host is a dedicated serverhost. You can also add a parameter to the JVM running your servlet engine.

   Add a -Djava.awt.headless=true to your JVM command-line. This works 
   fine unless the application tries to call methods which interrogate 
   the screen-size and so on. Using JDK1.4.1_03 I've got Cewolf working 
   under Linux for another application, so it should work for XPlanner too.
   - Neal Sanche

I've tried this approach and it worked on our Linux server. For Tomcat, add the option to the JAVA_OPTS environment variable before starting the server (edit the startup.sh program used to start Tomcat). There is also a program called Xvfb (X virtual frame buffer) that can be used as a replacement for a full X server. A few other potential solutions exist, but I'd recommend trying the JVM option first before exploring others.

6. Deploy the WAR file

Follow the instructions for your servlet container to deploy the xplanner.war file. For Tomcat, you place the xplanner.war file in the $CATALINA_HOME/webapps directory.

7. Start your servlet container and begin using XPlanner

You should be able to login as "sysadmin" with the password "admin". In most installations, you'll obviously want to change this password immediately. To get started, create an project with an iteration and start creating stories, tasks, etc. Have fun!

Configuring iCal Clients

To subscribe to a remote calendar using your iCal client use the following types of information (where user is your XPlanner user identifier).

URL: http://www.yourhost.com:8080/xplanner/ical/user.ics
User ID: user
Password: yourpassword

Running the Unit Tests

Use the unit.tests Ant target to run the XPlanner unit tests. The unit tests are built using JUnit and the JUnit jar file must be in the Ant class path when the tests are run.

Running the Acceptance/Functional Tests

You may also use Ant to run the XPlanner unit tests. Like the unit tests, the acceptance tests are built using JUnit and the JUnit jar file must be in the Ant class path when the tests are run. To run the acceptance tests:

1. Configure the xplanner.application.url in xplanner-custom.properties to reference your XPlanner test installation.
2. Set up the xplanner.test.user and xplanner.test.password properties in xplanner-custom.properties which the acceptance tests need to log into your Xplanner application
3. Run the acceptance.tests Ant task.