OFBiz Configuration, Deployment and Maintenance

Written By: Kane Deng
Email: [email protected]
Edited by Les Austin
Open For Business Site: http://ofbiz.apache.org/
Founders and Lead Architects: David E. Jones & Andy Zeneski
Last Updated: 04 August 2004

Table of Contents

  1. Introduction
  2. Building Blocks
  3. Setting Up a Database
  4. Downloading and Installing Java - java.sun.com
  5. OFBiz
    1. Getting OFBiz
    2. Deploying & Configuring OFBiz
    3. Keeping Up With OFBiz
  6. Restarting versus Run-time Changable
  7. The OFBiz  WebTools
  8. Performance & Reliability
  9. eCommerce Specific


This document describes the installation, configuration, and how to maintain OFBiz. You can install OFBiz from the start according to this document, and learn how to configure OFBiz, then learn how to maintain, and tune it for best performance. The first part will let you know some background knowledge necessary for learning OFBiz, and then will show you exactly how to use OFBiz.

Building Blocks

Operating System Recommendations


Linux is becoming more and more popular nowadays. Not only are many advanced developers using Linux, but also more and more web sites have begun to use Linux. With over 10 years development, Linux has become strong enough for enterprise level platform. At the same time, Linux's X Windows desktop environments are becoming more and more easy to use. So using Linux as OFBiz's system platform is not a bad choice. Sun and IBM (two of the biggest Java advocates) both consider support for Java running on Linux as one of their biggest tasks. The Linux version is almost always the first released when new Java version appears.



Unix Varieties

Sun Solaris, FreeBSD, SCO Unix, HP Unix, etc, are each varieties of Unix. They are all very stable, and have taken on the role of Internet backbones for many years. Linux is just an elder brother compared with them. But they are not easy to use, and each has its own special usage and configuration. Don't worry, most of the administration tasks are the same.

There are many big companies using them, and in spite of Linux is becoming more and more popular, big enterprises still trust commercial Unix more.

Windows Server

For enterprise applications, Windows server is a low-level servers, and is not very stable under high load. But it is enough for most of small-to-medium sized enterprise applications. Windows server is easy to learn, and easy to maintain. So many administrators love to use it, and it can be used in a development environment rather than a production environment.

Database Server Recommendations

MySQL MaxDB (was SAP DB)

Max DB (SAP DB) is another good open source 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 perhaps not as good in some ways as Oracle or some other commercial DBs, it has many development and production features and performs very well with a very complete and advanced feature set.

MaxDB is available under the MySQL AB "dual licensing" model. Under this model, users may choose to use MaxDB under GPL or under a commercial license.

Get MaxDB here:



Postgres is a very full featured database with transaction support, foreign keys, stored procedures, et cetera.

PostgreSQL is an object-relational database management system (ORDBMS), developed at the University of California at Berkeley Computer Science Department. Postgres pioneered many concepts that only became available in some commercial database systems much later.

Also, PostgreSQL can be extended by the user in many ways, for example by adding new data types, functions, operators, etc.

And because of the liberal license, PostgreSQL can be used, modified, and distributed by everyone free of charge for any purpose, be it private, commercial, or academic.

Get PostgreSQL here:


Oracle, Sybase, MS SQLServer, DB2, other commercial databases

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, Sybase, SQL Server and others and should work fine with any database that has a JDBC driver.

You can get more info on these databases from following sites:




MS SQLServer

Application Server Recommendations

Servlet & JSP Container

Jetty is a high quality 100% java HTTP Server and Servlet container. While Jetty can be used stand-alone, the project is not attempting to provide a full application server. Instead their approach is to develop Jetty as a component that can be used within other projects/products to provide HTTP and/or servlets.

From OFBiz 3.0, OFBiz began to use Jetty as an embedded HTTP Server, because Jetty is very easy to use. In previous versions, OFBiz developers had to maintain different deployment configurations for different servlet containers or J2EE servers, such as Jakarta Tomcat, Jetty, WebLogic, etc. This is a tedious job, and takes a lot of time. From OFBiz 3.0, they will only think of Jetty, and they can devote all their efforts to the core and component development of OFBiz. But many people are using old OFBiz versions, such as 2.00 or 2.11, they don't know how to deploy OFBiz 3.0 on their servlet containers other than Jetty.

OFBiz team will provide solutions for this problem, so just be a little patient : ). They can do good job.

Get Jetty here:

Tomcat is the servlet container that is used in the official Reference Implementation for the Java Servlet and JavaServer Pages technologies. The Java Servlet and JavaServer Pages specifications are developed by Sun under the Java Community Process. So maybe Tomcat complies with the Servlet and JSP standards the best. In theory, you can run your application on any other servlet containers if you can run it on Tomcat.

Tomcat is released under the Apache Software License, and intended to be a collaboration of the best-of-breed developers from the world.

You can configure Tomcat to work with Apahce easily; because they both belong to Apache.org, they can work together perfectly.

Get Tomcat here:


Orion, Weblogic & other commercial containers
There are many commercial servlet/JSP containers too, such as Orion, Weblogic, WebSphere, etc. These products are all powerful, not only implements standards, but also their own special features, such as clustering, fail-over, etc. They often are expensive and charged per CPUs, but many big companies like to use them, because they can provide great services, not only the products. Service is one of the shortcomings of open-source projects, and is somewhat difficult to be accepted by the commercial world.

But because of their own special features, it will be difficult to migrate onto others if you make full use of them. You will have to stick to using one if you choose it from the start.

Learn more about Orion here:


and Weblogic here:


Transaction Manager

JOTM is an open source transaction manager implemented in Java. For more than four years, JOTM has been the transaction manager of JOnAS, a J2EE server. It supports several transaction models and specifications providing transaction support for clients using a wide range of middleware platforms (J2EE, CORBA, Web Services).

JOTM embeds open source projects, such as CAROL, for transaction context propagation on both RMI/JRMP and RMI/IIOP, and XAPool, and XA-compliant JDBC connection pool. JOTM is bundled with OFBiz now.  Old OFBiz versions had been using Tyrex; it is said the OFBiz team had run into many problems with Tyrex, so they chose JOTM as a suitable replacement.

Since OFBiz only requires a Servlet container and a Transaction manager, using a full blown J2EE application can be too much overhead and at times difficult to configure. JOTM is easy to use, and simple to configure.

Learn more about JOTM here:


Orion, Weblogic & other commercial containers
These commercial containers all provide their own transaction manager. Using these containers may be more convenient because they provide both servlet containers and transaction managers. Open source containers often don't provide their own transaction managers, so you must make use of other open source transaction managers in these containers, such as you use Tomcat with JOTM.

Connection Pool


XAPool is an XA datasource connection pool: it implements javax.sql.XADataSource, and provides connection pooling facilities. XAPool allows one to pool objects, JDBC connections and XA connections. It comes from the Enhydra application server from Lutris. Now the project is hosted by the ObjectWeb consortium and managed by ExperLog.

XAPool has been successfully tested with MySQL, PostgreSQL, Oracle, SAP DB, MS SQL and InstantDB databases. The classic pool offers common and useful operations:

Learn more about XAPool here:
Orion, Weblogic & other commercial containers
These commercial containers all provide their own connection pools, and you can refer to their documentation for how to use.

Server Farm & Network Layout Recommendations

Single Server - all in one

If you download the complete OFBiz  package, it is bundled with everything you need to run immediately. This package can be taken as all-in-one single server. Single Server is easy to use, and installers don't do many tedious configurations, so itcan be used in a development environment. For a production environment, it is not suitable, because its scalability is poor.

Separate Application & Database Servers

One good choice is to separate the application server from the database server. The database bundled with OFBiz is HSQL, which is an embed database engine and can't support a high load; use it just for demonstration or development. For production environment, you can use MySQL or PostgreSQL, or other commercial databases mentioned above. You setup your database server first, then configure OFBiz running on one application server to access the database server.

Independent Static Content Server Option

For performance issues, you can run an independent static content server. There is a component named "content" in OFBiz, OFBiz puts all static files, such as .html, .gif, and .css, etc. under this component. This allows you to re-use common static contents between different applications. Just do some configuration on application servers, and let them point to the content server they will use.

Load Balanced Application Server Farm Options

IP Based Load Balancer

Session Aware Load Balancer

Application Server Specific Load Balancers
This is to run your application on multiple application servers, and lower the load on a single one. Load balancing will increase your application's high-availability, especially under mission critical environments. All application servers will access the same database server.

Tomcat 5 just added a load balancing feature, and almost every commercial servlet container provides their own load-blancing mechanism.

Load Balanced Database Options

Load balanced database is an advanced topic. This means to run one database on multiple database servers. It is said that MySQL will provide such capability, and it will threaten the biggest commercial database providers, such as Oracle, DB2, etc. Most of the commercial database providers have such capability.

Another choice is not database-based, but to add cluster handling on the JDBC level. There is an open source project named "C-JDBC", which means clustered JDBC. It is interesting; C-JDBC is database cluster middleware that allows any Java application (standalone application, servlet or EJB container, ...) to transparently access a cluster of databases through JDBC. C-JDBC provides a flexible architecture that allows you to achieve scalability, high availability and failover with your database tiers.

You can learn more about C-JDBC here:

Setting Up a Database

You should set up a database server before using OFBiz. There is an embedded Hypersonic SQL database in OFBiz, you don't need to do any configuration to run OFBiz. Maybe you want to use MySQL or PostgreSQL, or other commercial databases, you should first install and create a database for OFBiz.

Every database has detailed documentation on how to use, and it is not difficult to manage a database. Here one thing you should remember, every database has their own JDBC driver, .jar files. OFBiz already bundles some JDBC drivers in it, but for reducing problems, you should replace the original JDBC driver with the driver released with the database.

JDBC drivers in OFBiz:


Downloading and Installing Java - java.sun.com

Download Java at:


The installation is simple, but you should set JAVA_HOME after you install. This system environment parameter is very important, many applications will use it. You can set it in Control Panel if you are using Windows, and edit your .profile if your are using Unix. For convenience, you can add JAVA_HOME/bin to PATH too, this can simplify your use of Java.


Getting OFBiz

Download a Release
You can download a release, which is best for demonstration, evaluation, and low profile deployments.

OFBiz comes and runs by default with Jetty for a Servlet/JSP container and JOTM for a transaction (JTA) manager. A patched version of Minerva (included in CVS) is the current preference for a transaction aware connection pool, though as other options are made available that may change.

OFBiz can also be configured to run in different containers, but there may be issues with certain quirks that other containers have, especially with servlet containers. We have always been able to find work-arounds for these, but they also seem to keep on appearing, so that is just something to watch for.

We are not maintaining sample configurations in CVS any more because it became too difficult to keep up with changes in new versions for a dozen different app servers. We may eventually start this again if there is sufficient demand and corresponding contributions. If you are looking for a good commercial J2EE app server, Orion is a good place to start, but we recommend trying out Jetty and JOTM and see if they meet your needs.

Download OFBiz releases here:

ofbiz.apache.org/  (and see the download section on the left side of the page)

Getting from CVS
If you want to keep up with OFBiz's development or you are doing some customization on OFBiz, you can get it using CVS, then you can update using cvs at any time.

If you are using command line CVS, you can get OFBiz using following commands:
cvs -d :pserver:[email protected]:/cvs login

press "Enter" if cvs prompts you for password, then using this command:

cvs -d :pserver:[email protected]:/cvs checkout ofbiz

If you are using WinCVS or other GUI cvs client, you should set CVSROOT parameter in Preferences, set as follows:

 :pserver:[email protected]:/cvs

then you can login and check out OFBiz.
For more about how to use CVS, you can refer to this site: http://www.cvshome.org/

You don't need to build if you download the OFBiz release, but you have to build if you get OFBiz with cvs. Before building you should download and install Ant. For more about Ant, see:


They have great documentation on how to install and use ant; just install it according to their manuals.

You can start to build OFBiz if your ant installation is ok, just go to the OFBiz directory in a command line window, and key in "ant" command. Ant will build OFBiz immediately. The whole building process may last for several minutes, it depends on your computer.

Your OFBiz is ready to go after you build it.

Deploying & Configuring OFBiz

Database Configuration

jndiservers.xml is used to configure JNDI parameters. You may be familiar with jndi.properties if you have used JNDI. You can take jndiservers.xml as a collection of several jndi.peroperties, and you can define several JNDI servers in a single file and don't need to maintain multiple jndi.properties files.

You can define your JNDI configurations in jndi.properties, OFBiz will take it as "default" configuration file. You can see this line in jndiservers.xml...

    <!-- this jndi-server has no parameters so the factory will use the default
InitialContext constructor which gets these values from the jndi.properties file -->
<jndi-server name="default"/>
It tells you if you are using "default" jndi-server, OFBiz will get parameters from jndi.properties.

You can configure OFBiz get database transaction manager using JNDI, there are following lines in entityengine.xml...

    <!-- Use this one for JNDI -->
<!-- NOTE: to use the JndiFactory you must specify the necessary JNDI properties -->
<transaction-factory class="org.ofbiz.entity.transaction.JNDIFactory">
<user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/>
<transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/>

This is using the "default" JNDI server, it means you can define your JNDI parameters in jndi.properties. Certainly, you can modify the jndi-server-name to use other JNDI servers defined in jndiservers.xml, such as
    <jndi-server name="OpenJMS"

<!-- Note that in most cases this is not necessary or desired for Orion, the default above is easier/better -->
<jndi-server name="localorion"

<!-- Note that in most cases this is not necessary or desired for Weblogic, the default above is easier/better -->
<jndi-server name="localweblogic"

The above lines define OpenJMS, localorion, and localweblogic, for all three JNDI servers.


Database setup is done in the entityengine.xml file, entityengine.xml is located in the ofbiz/framework/entity/config directory. There are many options there which are described in the Entity Engine Configuration 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.

The default config in entityengine.xml is

    <delegator name="default" entity-model-reader="main" entity-group-reader="main" entity-eca-reader="main" distributed-cache-clear-enabled="false">
<group-map group-name="org.ofbiz" datasource-name="localhsql"/>

the datasource "localhsql" is defined as follows in entityengine.xml:

    <datasource name="localhsql"
<read-data reader-name="main"/>
<!-- <jndi-jdbc jndi-server-name="localjndi" jndi-name="java:/HsqlDataSource" isolation-level="ReadUncommitted"/> -->
<!-- <jndi-jdbc jndi-server-name="default" jndi-name="comp/env/jdbc/xa/localhsql" isolation-level="ReadUncommitted"/> -->
<!-- Orion Style JNDI name -->
<!-- <jndi-jdbc jndi-server-name="localjndi" jndi-name="localhsqlDataSource"/> --> <!-- Weblogic Style JNDI name -->

There are other datasource definitions in entityengine.xml too, which includes HSQL, Cloudscape, MySQL, PostgreSQL, Oracle, SyBase, SAP DB, MS SQL, etc. You can change the datasource definition for a different database type, and then modify the default delegator to use it, just the same as using HSQL above.

Eg. if you want to configure OFBiz to use MySQL, just modify the following lines according to your MySQL server...

    <datasource name="localmysql"
<read-data reader-name="main"/>
<!-- <jndi-jdbc jndi-server-name="localjndi" jndi-name="java:/MySqlDataSource" isolation-level="Serializable"/> -->

change the jdbc-uri, jdbc-username, and jdbc-password's values to suit your database. Then modify this line:

    <delegator name="default" entity-model-reader="main" entity-group-reader="main" entity-eca-reader="main" distributed-cache-clear-enabled="false">
<group-map group-name="org.ofbiz" datasource-name="localhsql"/>

and change datasource-name from "localhsql" to "localmysql".

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/framework/entity/fieldtype directory.

Default data can be loaded automatically once the server has been started by going to a JSP, which will be explained in the WebTools section.

J2EE Application Server Configuration
Servlet & JSP Container

Since 3.0, OFBiz embeds Jetty as its default Servlet & JSP container. So you don't need to do any special configuration if you use the embedded Jetty. Now it is not easy to deploy OFBiz onto other Servlet & JSP containers, and you'd better use the embedded Jetty for OFBiz 3.0. There are developers who are contributing programs or documents on how to deploy on other containers, just be a little patient. OFBiz is very portable, and it is not difficult to run on other containers.

Transaction Manager

OFBiz 3.0 is using JOTM as its transaction manager, previous versions had been using Tyrex.

We configure the transaction manger in entityengine.xml, there are the following lines in entityengine.xml...

    <!-- the transaction factory class to use, one is needed for each way of getting JTA interfaces -->
<!-- Use this one for JOTM -->
<transaction-factory class="org.ofbiz.entity.transaction.JotmFactory"/>

<!-- Use this one for JNDI -->
<!-- NOTE: to use the JndiFactory you must specify the necessary JNDI properties -->
<transaction-factory class="org.ofbiz.entity.transaction.JNDIFactory">
<user-transaction-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/>
<transaction-manager-jndi jndi-server-name="default" jndi-name="java:comp/UserTransaction"/>

OFBiz will use JNDI to get transaction manager as default, and you can use the JotmFactory by uncommenting the above lines.

OFBiz will start JNDI service first, then bind the transaction object under JNDI naming service using name "java:comp/UserTransaction". Other programs will get the transaction by accessing the JNDI using "java:comp/UserTransaction". You can see the ofbiz/base/config/ofbiz-containers.xml to learn how OFBiz starts JNDI service. There are the following lines in ofbiz-containers.xml file...

    <!-- load JNDI/JOTM -->
<container name="jotm-container" class="org.ofbiz.entity.transaction.JotmContainer"/>

JotmContainer will start Carol naming service first, then create a Jotm object, and then bind the transaction object to Carol naming service using the name "java:comp/UserTransaction".

Connection Pool

OFBiz uses both Minerva connection pool and DBCP connection pool, and will try to obtain a connection from Minerva first, and will use it if can. If OFBiz can't get a connection from Minerva, it will try DBCP, and if DBCP fails too, OFBiz will try to obtain a connection using plain JDBC.

You can see following configuration in entityengine.xml...

    <datasource name="localmysql"
<read-data reader-name="main"/>
<!-- <jndi-jdbc jndi-server-name="localjndi" jndi-name="java:/MySqlDataSource" isolation-level="Serializable"/> -->

OFBiz will check jndi-jdbc first, and will obtain connections from the JNDI service if you configured it. The above lines haven't configured jndi-jdbc, the lines have been commented. But if you configured jndi-jdbc and OFBiz can't obtain a connection from it, OFBiz will try to get connections using Minerva and DBCP, as configured in inline-jdbc.

You can set the connection pooling parameters in inline-jdbc; currently, there are pool-maxsize, pool-minsize, two parameters. Set these two parameter like this:

    <datasource name="localmysql"
<read-data reader-name="main"/>
<!-- <jndi-jdbc jndi-server-name="localjndi" jndi-name="java:/MySqlDataSource" isolation-level="Serializable"/> -->

The above setting means there will be 2 connections in the pool at the minimum and 20 connections in the pool at the maximum.

JMS Configuration


Production Oriented Settings
URL Settings

You can define URL settings with the ofbiz/framework/webapp/config/url.properties. The HTTPS port setting is as following:

# HTTPS Port (Secure port)

We can set the force.https.host to redirect HTTPS requests to other servers. The HTTP setting is :

# HTTP Port (Not Secure port)

We can set the force.http.host to redirect HTTP requests to other servers, but this is not necessary.

Maybe you want to move static contents to other servers, and this can lower load on this server. The settings are:


If the above two settings are empty, OFBiz will use current server. You can set those lines above as follows to redirect static page requests to another server.


Detailed settings of content component are in ofbiz/applications/content/config/content.properties file. The current settings are as follows:


You can modify these settings according to your needs.

Cache Settings & Analysis


Cache handling is very important for software production running environments.

The cache.properties file contains cache settings used by UtilCache class. Default cache parameters can be passed in when a cache is created but if cache parameters exist in this file for the given cache name then they will be loaded from the cache.properties file.

There are three optional properties in this file for each named cache: {cache-name}.maxSize (whole number), {cache-name}.expireTime (whole number) and {cache-name}.useSoftReference (true or false). The maxSize property specifies the maximum number of entries in the cache, but does nothing with respect to the size of each cache entry. The expireTime property specifies how long in milliseconds each cache entry will be valid. If either value is 0 the feature will be disabled, i.e. unlimited cache size or no expire time.

The useSoftReference property is used to specify, true or false, whether soft references should be used for cache entries.Soft references help keep large caches from taking too much memory by allowing the garbage collector to clear these entries when more memory is needed.

If the values are not specified and are not passed to the UtilCache constructor, the values in the default.maxSize, default.expireTime and default.useSoftReference properties will be used.

There are some development mode cache settings...

# Development Mode - comment to cache BSH scripts, etc

These settings are used to help you develop applications. OFBiz will reload BSH scripts or other resources every time you use in your applications if you set as above, it can avoid restarting OFBiz every time you modified a BSH or other scripts, save your time.You should comment the above lines if you want to run OFBiz applications under production environments.

WebTools Cache UI

Restarting versus Run-time Changable

The OFBiz WebTools

Performance & Reliability

eCommerce Specific