The Open For Business Project: General Setup

Table of Contents

• Introduction
• Quick & Easy Setup
• External Packages Setup
• Paths
• File Locations and Building
• Running
• Database Setup
• Alternative Deployment Options

Introduction

This document describes an initial setup process and configuration options for the Open For Business Project.

Quick & Easy Setup

You can get up and running quickly by downloading the OFBiz Complete distribution and following some simple instructions. For more options and explanations, see the rest of this document.

1. Download and install the Java 2 v1.3 or later JDK (not the JRE) from Sun's Java site, and make sure your JAVA_HOME environment variable is set
2. Download the OFBiz Apps archive and unzip it in the directory of your choice. This should create one sub-directory: ofbiz. This will be the OFBIZ_HOME location.
3. Start OFBiz with embedded Jetty by going into the ofbiz directory and then running "%JAVA_HOME%\bin\java -jar ofbiz.jar" for Windows, or "$JAVA_HOME/bin/java -jar ofbiz.jar" for Linux/Unix.
4. Open a browser and go to http://127.0.0.1:8080/ecommerce for the ecommerce application or http://127.0.0.1:8080/webtools for the WebTools application or http://127.0.0.1:8080/catalog for the Catalog Manager application.
5. Have fun with it! You are running on a Java database, which isn't the best for deployment, but it's great for a demo...
6. For more detailed options and configuration information, read on!

External Packages Setup

You will also need the Java 2 version 1.3 or 1.4 JDK (NOT just the JRE) from java.sun.com, as is expected for a Java application.

Open For Business can be run with either a simple servlet engine alone (like Tomcat) or with a full J2EE container (like Orion or JBoss & Jetty together). A full J2EE application server is also useful for services other than the basic EJB container, such as JNDI, connection pooling, transaction management, various resource and configuration management conveniences and so forth. Many other J2EE application servers are available for these sorts of features, and Open For Business should be easily adaptable to various ones.

Jetty is the current default application server for Open For Business. JTA (distributed transaction) support is currently done with JOTM, but could also be provided by JBoss or another J2EE application server.

Jetty can be downloaded at jetty.mortbay.com, and you will generally want the latest version of the Jetty 4 series. The latest version of OFBiz has been tested on Jetty 4.2.9. If you download an OFBiz package with these included, you of course don't need to download them again. It should run in place, as is.

You can download JBoss, a complete J2EE application server from sf.net/projects/jboss, you will generally want the most recent version.

Things will be much easier if you have Ant installed, which can also be downloaded from the jakarta.apache.org site listed above. Instructions are available on the Ant site for installing the application. Just make sure that 'ant' is on the system execution path and can be run from the command line.

To run the Ant scripts, and Jetty, make sure the various environment variables are set as described below.

Paths

The last step is to make sure the directories are correct, especially the JDK path. This is done by making sure the various environment variables are set. These directories are setup as follows:

File Locations

If you have just checked out the OFBiz modules from CVS you will beed to copy the Ant build.xml file from OFBIZ_HOME/setup/ofbiz/build.xml to OFBIZ_HOME. All of the jar files needed to build OFBiz are included in the 'lib' module. Some of these need to be included on the classpath when running, but not all. Some are only included to make it easier to build the project and to provide a consistent platform to work from.

Here is a list of the directories that need to be, or whose contents need to be, on the classpath for running:

In addition to these certain less complete app servers will need some addition classes from the ofbiz/lib/compile directory. For instance, Jetty needs: xerces.jar, activation.jar, mail.jar, and jdbc2_0-stdext.jar.

If this list looks worrysome to you don't worry too much about it. We have startup scripts and config files for various app servers to set up these paths and with the embedded Jetty startup class everything is done "auto-magically".

There may be additional JARs and other resources that you need to put on your classpath, such as JDBC drivers. We do include JDBC drivers for Postgres, MySQL, SAP DB and of Hypersonic SQL, which comes with it.

Running

To setup the path to the OFBiz directory and pass it into the Java application the -D argument on the Java command line must be used. To make this easier ofbiz.sh and ofbiz.bat have been provided which set some things up before calling catalina.sh or catalina.bat, respectively. These ofbiz scripts should be put in catalina/bin, and you can use the run, start, stop, etc. parameters on the command line.

The default data can be loaded by going to the following URL: http://localhost:8080/webtools/control/main, and then click on the link for data loading, or go to http://localhost:8080/webtools/control/install directly. Since there can be multiple servers depending on the name of the entity group, you must enter the entity group name so the JSP knows which files to load to which server, as setup in the entityengine.xml file. This JSP loads all .sql and .xml files in the directories specified in the entityengine.xml file for the given group name. The default group name for all of the default entities in OFBiz is "org.ofbiz.commonapp", which you will notice pre-populated in the form on the install page. Just click on "Load Data", and after reviewing the summary of what it will do, click on "Yes, Load Now", and be patient as the data is loaded into your database.

That data loader can load XML Entity Engine files or SQL files. For SQL files the data loader page expects ';' separated SQL INSERT statements. These INSERT statements should list all of the column names for each value. INSERT statements are generally pretty generic, so this should work for most databases. These statements are run through JDBC, and use the JDBC data mappings for genericity.

Go to http://localhost:8080/webtools/ for the Web Tools. For secured areas of the site, the default admin account information is in an XML data loader file. The default is 'admin' for the username, and 'ofbiz' for the password. Be patient when you hit each page for the first time, they all need to be compiled when it is run initially.

The other applications can be reached at similar looking URLs. For instance, the ecommerce application can be accessed at http://localhost:8080/ecommerce/.

Database Setup

Database setup is done in the entityengine.xml file. There are many options there which are described in the Entity Engine Guide.

The OFBiz Apps archive comes with Hypersonic SQL, a Java database that runs in memory. This database is good for demonstration purposes because it is easy to setup and use. It is not meant to handle large data sets and does not provide the same performance or scalability that a major database would.

There are many open source databases that will scale well and deliver good performance. The two most popular are MySQL and PostgreSQL. Postgres is a very full featured database with transaction support, foreign keys, stored procedures, et cetera. MySQL is known for performing very well but the transaction support is limited (and improving) and there is no support for stored procedures. The stored procedures issue is not a big deal for OFBiz as it stands now because they are not used, but transaction support is VERY important for production business systems. Another good open source option is SAP DB, and it deserves special mention. SAP decided to start making it easier for users to use commercial databases instead of their own and open sourced their database, SAP DB. While maybe not as good as Oracle or other commercial DBs it has many development and production features and performs well.

Commercial databases are also supported. If you have database licenses for other needs, or have major in-house familiarity with and support for a certain commercial database, then there is no reason not to take advantage of that. OFBiz has been tested with Oracle and should work fine with any database that has a JDBC driver.

There is no need to run any SQL scripts to create the tables or populate them with the default data. The entity engine can create missing tables or fields when the server starts up and does so if the appropriate property is set in the entityengine.xml file. This is the file that configures the servers for the entity engine.

For the table creation routine to work properly, the field types must be set up by specifying the corresponding fieldtypeXXX.xml (where XXX is the database name) file for the server in the entityengine.xml file. These fieldtypeXXX.xml files are located in the ofbiz/commonapp/entitydef directory, along with the entitymodel*.xml files which contain database independent entity definitions.

Default data can be loaded automatically once the server has been started by going to a JSP, which is listed below in the Running section.

Alternative Deployment Options

Future releases of The Open For Business Project will support alternative deployment options, for use with application servers other then Jetty/JOTM. The webapp directory in each module is a fully self sufficient web application. Each of these may be packaged into a WAR file and deployed normally. Please keep in mind the OFBiz required libraries must be in the global classpath. An alternative method of deploying with Catalina would be not to modify the server.xml file, but instead place the required files in the /lib and /classes directory as described above and deploy the WAR files in the /webapps directory.

Sample configuration files and start scripts for various app servers are available in the setup module of OFBiz (see ofbiz/setup in the distro). Open For Business uses a few primary components of J2EE and needs a container for these components. The components needed for OFBiz include Servlet 2.3, JSP 1.2, and a JTA implementation with a JDBC XA Wrapper and Connection Pool.

The following configurations have been tested and are included:

Full testing and deployment instructions for WebSphere, iPlanet, ServletExec, and others are forthcoming in future releases. If you are interested in helping with this please contact one of the project admins.