Development Stack Setup

Summary

To check which are the recommended and supported versions of each stack component for different Openbravo versions, check System_Requirements document.

This article explains in detail how to install and configure the whole stack required for a Openbravo ERP development environment, including:

• PostgreSQL.
• Oracle.
• Sun JDK.
• Apache Ant.
• Apache Tomcat.

The whole guide is valid for all the hardware architectures the stack supports, such as x86 or x86_64. A minimum of 2GB or RAM is recommended for x86 and 3GB for x86_64.

Motivation

A development setup has different needs than a production environment. The main goal is to make the developer's life as easy as possible, while increasing the productivity.

Some of the components are configured in the same way as in a production system. In those cases a link to the production environment setup is provided.

Operating System

We recommend using Linux or another UNIX-alike flavor (*BSD, OS-X, OpenSolaris). The amount of useful development tools provided by these operating systems are vastly superior to the rest, at least regarding Openbravo ERP.

Create an unprivileged user for you in the operating system. Once the environment is configured, avoid using the root (superuser, admin) user for anything related to Openbravo ERP development. Do not compile as this root!

Regardless of our OS preference, we strongly advise the developers AGAINST using a new OS that they are not comfortable with while learning Openbravo. Our experience shows that learning a new OS and Openbravo at the same time yields poor results and low productivity! Instead, stay on the OS you already know and learn Openbravo. Later, you can switch to another OS if so required.

PostgreSQL

Follow the installation steps to install PostgreSQL, configure an admin (postgres) password, and setup the MD5 password authentication. Additionally, make sure the postgresql-contrib modules is installed (UUID requires it). Once it is installed, and to make the database accessible from anywhere, so that external developers or yourself can access it easily with PgAdmin3, psql or any other development tool. Locate and edit the postgresql.conf file, and uncomment the following line, assigning this new value:

listen_addresses='*'

This makes the database be listening in all the interfaces available in your system and not only in localhost (default).

Locate and edit the pg_hba.conf file, and add this line at the end:

host    all         all         0.0.0.0/0          md5

Or if you want more security you can change the 0.0.0.0/0 with the concrete IP that you want to give access for example 1.2.3.4/32.

Just for safety purposes, this assumes you have a firewall in your local LAN preventing outsiders to access the database.

As an example, in Ubuntu 12.04, these file are located in /etc/postgresql/8.4/main, assuming that you have installed PostgreSQL 8.4.x

Oracle

Do not use Oracle XE. It's 4GB storage limitation makes it useless for heavy development in a few days, and it has a bug that happens usually when using Openbravo ERP. Therefore, the recommended Oracle edition is Standard Edition.

The number of open cursors should be 3000 at least. To verify this:

SELECT value FROM v$parameter WHERE name = 'open_cursors';

To increase it:

ALTER SYSTEM SET open_cursors = 3000 SCOPE=BOTH;

Make sure that the number of processes is 150 at least. To verify this:

SELECT value FROM v$parameter WHERE name = 'processes';

To increase it:

ALTER SYSTEM set processes=150 SCOPE=SPFILE;

And restart Oracle after doing this change.

Sun JDK

Follow the installation steps to set up the Sun JDK.

The IBM JDK works well too, but almost all the developers use either OpenJDK or Sun's.

Apache Ant

Follow the installation steps to set up the Apache Ant. Since version 2.50 Ant needs its memory settings to be tweaked. Otherwise some basic tasks like a compilation are likely to fail. Assuming you are using Bash as your shell, append the following line to your ~/.bashrc file (or add it as an environment variable):

<source lang="bash"> export ANT_OPTS="-Xmx1024M -XX:MaxPermSize=128M" </source>

Don't include XX:MaxPermSize if using Java 8 or higher.

See the Apache Tomcat section for an explanation of what these options mean.

Close your current shell session and open a new one to apply changes.

Apache Tomcat

Do not use the Tomcat version provided by your operating system's package manager

The packaged version of Tomcat is very unfriendly for development due to web application deployment specifics. Packaged versions of Tomcat are meant for production environments. This especially applies to Linux distributions.

Instead, download the official distribution, and extract the files in your home directory. We recommend you to place it in ~/servers/tomcat.

Every Linux distribution and operating system packages Tomcat in a different way, with different security settings, permissions, memory setting and logging configuration. Some of these configurations are not development friendly. This is the reason of the recommendation to use the official distribution.

The default memory settings of Tomcat are not enough for a proper Openbravo ERP functioning. Thus append the following line to your ~/.bashrc (or add it as an environment variable):

<source lang="bash"> export CATALINA_OPTS="-Djava.awt.headless=true -Xms384M -Xmx512M -XX:MaxPermSize=256M" </source>

• -Djava.awt.headless: this setting controls running the environment with a headless implementation. In Openbravo ERP the client is always a web browser, so the JVM does not need to run any graphical window at all.

• -Xms: this setting controls the initial size of the Java heap. Properly tuning this parameter reduces the overhead of garbage collection, improving server response time and throughput.

• -Xmx: this setting controls the maximum size of the Java heap. Properly tuning this parameter reduces the overhead of garbage collection, improving server response time and throughput.

• -XX:MaxPermSize: Do not include this option if using Java 8 or higher. It controls the section of the heap reserved for the permanent generation, and holds all of the reflective data for the JVM.

Note: In the Openbravo Debian/Ubuntu package, these settings are located in /usr/share/openbravo-erp/etc/openbravoerprc.

These options are the same ones as for production environment, except for the -server option. This is useful only in production servers, because it makes the JVM to use the optimizing compiler instead of the standard one. And while this change increases significantly the performance of the server, it takes longer to start up. And deployment speed is something that a developer appreciates.

In order to avoid the "Unable to find a javac compiler; com.sun.tools.javac.Main is not on the classpath. Perhaps JAVA_HOME does not point to the JDK" error when trying to compile the application from Tomcat using the Openbravo ERP web interface, add the tools.jar library to Tomcat's classpath:

<source lang="bash"> cp $JAVA_HOME/lib/tools.jar ~/servers/tomcat/lib/ </source>

In order to avoid Tomcat from auto-reloading itself, comment the WatchedResource line in conf/context.xml: <source lang="xml"> </source> Configure a username and password for the Tomcat Manager, by replacing the conf/tomcat-users.xml file with these contents: <source lang="xml">

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager"/>
  <role rolename="admin"/>
  <user username="admin" password="admin" roles="admin,manager"/>
</tomcat-users>

</source>

Replace password="admin" with your own password.

Finally, to start and stop tomcat use the following commands: <source lang="bash"> cd ~/servers/tomcat/bin ./startup.sh ./shutdown.sh </source>

Mercurial

Follow the Mercurial manual for Openbravo developers to install and configure it.