ERP/2.40/Openbravo Basic Network Administrator's Manual

Introduction

Openbravo Basic Network is a service that gives you access to support and bug fixes for your Openbravo ERP Installation. This document explains how to prepare your system, download, install and configure Openbravo Basic Network.

System requirements

To successfully install the solution stack and Openbravo Basic Network, it is recommended that your system meets the following criteria:

• Operating system: Openbravo Basic Network supports Windows, Linux, BSD and OpenSolaris.
• Architecture: x86, x86_64.
• RAM: 2GB or more.
• CPU: Core 2 Duo or equivalent, operating at a minimum 2Ghz.
• Hard Disk: 50GB or more operating at 7200rpm or 10000rpm.

Installing the solution stack

Before you begin installing Openbravo Network, you must install the following:

• Sun Java Development Kit (JDK)
• PostgreSQL or Oracle database
• Apache Tomcat
• Apache Ant

Follow the instructions in the Openbravo Environment Installation Guide.

Downloading Openbravo Basic Network

Openbravo Basic Network is available as source code which you can download from Subversion. You must have a Subversion account in order to download the code.

Find out more about Subversion

The download and installation process described in this document can be used on Windows and Linux operating systems, both for desktop computers and servers. The community installer is not recommended for Openbravo Basic Network.

Downloading the code

1. Download and install the Subversion Client of your choice.
2. From the command line, navigate to the directory to which you want to download the code.
3. Execute the following command:

   $ svn checkout https://dev.openbravo.com/svn/openbravo/tags/tag_name

   where tag_name is the name of the tag you want to download.

   If you are downloading a private tag, the system asks for your Subversion username and password. The Subversion username and password are supplied by Openbravo when you subscribe to Openbravo Basic Network.

The code is downloaded to your machine.

Note: If you do not want to check out this version, you can browse for other tags using a web browser. Launch https://dev.openbravo.com/svn/openbravo/tags in your chosen browser.

Configuration

There are two files that you must configure in order to build Openbravo Basic Network correctly:

1. • Openbravo.properties
   • log4j.lcf
2. In the openbravo-240/config/setup-tool directory, launch the configuration wizard:
   • Windows:launch the setup-properties-windows.exe file.
   • Linux: make the setup-properties-linux.bin file executable and run it:

     chmod +x setup-properties-linux.bin
     

     ./setup-properties-linux.bin

The configuration wizard launches. For GUI systems, the wizard is GUI based. For command line systems, the wizard is text-based. The wizard detects the correct display mode for your system automatically.

Installation and Deployment

1. To install the source code and create the database tables from the .xml files, execute the following Ant command from the command line:

   $ ant install.source

   The BUILD SUCCESSFUL message appears.

2. Deploy the openbravo.war file to the Apache Tomcat context directory (usually webapps)execute the following Ant command from the command line:

   $ ant deploy

3. If you are using PostgreSQL as your database, you must clean the database before you access Openbravo Basic Network, to prevent performance problems. From a command line, run the following command:

    vacuumdb -f -z -h hostname -d dbname -U username

   where hostname is the hostname of your database server, dbname is the database name (by default this is openbravo), and username is the name of the DB user (by default this is tad).

Accessing Openbravo Basic Network

The URL used to access Openbravo Basic Network follows the following format:

http://hostname:port/context_name

For example:

http://localhost:8080/openbravo

Subscribing to Update Notifications

It is strongly recommended that you subscribe to the Openbravo update and security distribution lists. The on-update-announce@openbravo.com distribution list notifies you when maintenance packs are available. The on-security-announce@openbravo.com notifies you of important security updates.

• To join on-update-announce@openbravo.com distribution list, send a blank e-mail to the update distribution list.
• To join the on-security-announce@openbravo.com distribution list, send a blank e-mail to the security distribution list.

Alternatively, you can subscribe online via the subscription site:

• Update subscription
• Security subscription

Applying Maintenance Patches

Openbravo ERP maintenance patches are released in form of Subversion tags, following this structure:

https://dev.openbravo.com/svn/openbravo/tags/<tag_name>

Where tag_name can be 2.40, 2.40MP1, 2.40MP2, etc.

To apply a maintenance pack, follow these steps:

Check the current version

Before upgrading to a new maintenance pack, check which version is currently installed:

1. From the command line, change directory to the directory where the Openbravo source code is checked out.
2. Type the following command:

   $ svn info

   Two lines of output appear, with current version on the second line. For example:

   URL: https://dev.openbravo.com/svn/openbravo/tags/r2.40MP2

   indicates that the current version is 2.40MP2.

Export the database

Before updating the working copy to a newer release, the database must be exported to XML files, so that any changes to the database are retained when the patch is applied. Use the Ant command:

$ ant export.database

Apply the maintenance pack

1. To download a maintenance pack, use the command:

   $ svn switch https://dev.openbravo.com/svn/openbravo/tags/<tag_name>

   where <tag_name> is the tag number of the maintenance pack, for example to upgrade to the r2.40 version the command would be:

   $ svn switch https://dev.openbravo.com/svn/openbravo/tags/r2.40

   The changes in r2.40 are merged with any customizations you have made.

2. When the pack has been downloaded, check if there are any source code conflicts using the following command:

   $ svn status

   Files that have been modified without conflict are marked as M (modified).

   Files that have conflicts are marked with a C. If there are conflicts, you must resolve them before you can proceed. For information on how to resolve conflicts, consult the source code conflicts section of the Openbravo SMB One Administrator's Manual. If there are no conflicts, update the database and deploy the code.

3. Edit the config/Openbravo.properties file and change the application.version property to the version you are updating to, e.g. 2.40MP5.

Update the database

The database must be updated with the latest applied maintenance pack. Use the command:

$ ant update.database

Build and deploy the code

1. Build the upgraded Openbravo ERP:

   $ ant core.lib wad.lib trl.lib compile.complete war

2. Deploy the build to Tomcat:

   $ ant deploy

Developer guidelines

New development is required if you want to change the system behavior of Openbravo Basic Network. For example, you may want to add a new window or modify a particular process. Development is an iterative process that makes the system potentially unstable, so development should always take place outside of the production environment. Any change that requires compilation should also take place in the development environment first.

Openbravo Basic Network comprises a single Openbravo ERP environment, which is intended for production. It does not provide alternative environments for development and testing purposes, so you must create these alternative environments on other machines. It also describes how to synchronize these environments.

It is important that you do not perform any development activity on the production environment, although it is safe to perform basic configuration tasks such as defining document types, roles and clients. You are strongly advised to perform any development tasks in a separate development environment. For complex developments and for organizations with strict change management policies, you may also need to move changes into a testing environment where they can be validated by end users before they go live in the production environment. In simpler situations moving the developments from the development environment to the production environment may be sufficient.

The development environment does not need to be a mirror of the production environment and it does not need an Openbravo ERP installation, it just needs the necessary tools to develop Openbravo ERP. For more information about installing these tools, consult the Openbravo environment installation page of the wiki. It may also be useful to have a testing environment. The development environment is used for testing purposes by the developer while the testing environment is the system where the end users can test the application and the new developments.

There are two ways to copy an Openbravo ERP instance to a new environment:

• By copying the source code in which case user data will not be copied to the new environment. DBSourceManager is a tool that exports database content (schema objects and data) to XML files and creates or updates a database from those XML files. Exported data is split into source data (application dictionary information) and user data. You can use DBSourceManager to export data from an Openbravo database and copy the data required to build an identical system without the user data. To ensure that the most recent version of the database is copied export it to XML files just before copying them to the new environment. This method is the recommended way to create a development environment.

• By creating a mirror copy of the existing Openbravo ERP and restoring it to a new environment. This method will export the user data as well as the system itself, and is more appropriate for creating a testing environment than a development environment because it copies user data as well as the database itself.

A typical schema for the development process looks like this:

The numbers 1-4 show the development processes taking place:

1. Creating and updating the development environment: sources and the database of Openbravo Basic Network are copied from the production environment to a development environment. This means that development can take place without disrupting the production environment.
2. Development: changes are coded and tested in the development environment.
3. Creating and updating the test environment: a testing environment is created as a mirror of the production environment using a backup and restore technique. The changes are then copied from the development environment to the testing environment. This step is recommended but not mandatory.
4. Deployment: when the changes pass testing, they are copied from the development environment to production environment.

The coloured lines represent the differing levels of environment setup from the simplest to the most complex:

• Production environment only (green). This is the recommended approach for a system with only configuration and no development. Only process 5 takes place.
• Production and development environments (blue). This is the recommended approach for very simple developments that do not require end user testing before going into production. This includes processes 1, 2 and 4.
• Production, development and testing environments (red). This is the recommended best practice for sophisticated development. All four processes are needed to run a system with these three environments.

Creating a new development environment

The first stage of the process is to copy the working Openbravo ERP application from the production environment to the development environment. It is important to ensure that the development environment is up to date with the production environment, otherwise previous changes may be lost when you deploy the new development in the production environment.

To create a development environment, follow these steps:

1. In the production environment, execute the following command:

   $ ant export.database

   This Ant task exports the database code (i.e., schema objects such as tables, PL/SQL code and models as described in the Application Dictionary).

2. Copy the following files and folders from the production environment to the development environment:
   • attachments
   • build.xml
   • config
   • database
   • legal
   • lib
   • log4j.lcf
   • src
   • src-core
   • src-db
   • src-trl
   • src-wad
   • web
3. In the production environment, execute the following command:

   $ tar zcf /tmp/sources.tgz attachments/ build.xml config/ database/ legal/ lib/ log4j.lcf src src-core/ src-db/ src-trl/ src-wad/ web

4. In the development environment, execute the following commands:

   $ scp openbravo@obnserver:/tmp/sources.tgz /tmp
   

   $ mkdir AppsOpenbravo

   $ cd AppsOpenbravo

   $ tar zxf /tmp/sources.tgz

5. Manually edit the configuration files on the development environment. See Openbravo.properties article. Edit the following files:
   • config/Openbravo.properties.
   • log4.lcf

   In the configuration files, edit the following configuration information:

   • Database name (the SID).
   • Database IP address (or host name).
   • Database superuser password.
   • Openbravo database username and password.
6. Create the database and compile it using the the following commands:

   $ ant create.database
   

   ant core.lib wad.lib trl.lib compile.complete.development

7. In the development environment, restart the Tomcat service. You can now access Openbravo ERP on the development environment via a web browser.

Updating an existing development environment

If you have already set up and configured a development environment, it is important to keep it up to date to prevent losing changes from previous development when new developments are deployed to the production environment. To update the development environment:

1. Copy the following files and folders from the production environment to the development environment:
   • attachments
   • database
   • src
   • src-core
   • src-db
   • src-trl
   • src-wad
   • web
2. In the production environment, execute the following command:

   $ tar zcf /tmp/sources.tgz attachments/ database/ src/ src-core/ src-db/ src-trl/ src-wad/ web/

3. In the development environment, execute the following commands:

   $ scp openbravo@obnserver:/tmp/sources.tgz /tmp
   

   $ cd /opt/AppsOpenbravo

   $ tar zxf /tmp/sources.tgz

4. Update and compile the database using the following Ant commands:

   $ ant update.database
   

   ant core.lib wad.lib trl.lib compile.complete.development

5. In the development environment, restart the Tomcat service. You can then access Openbravo Basic Network via a web browser.

Creating a mirror copy of the production environment

The procedures described above for creating and updating a development environment do not copy transactional or master user data into the development environment. In most situations, transferring user data from the production environment to the development environment is not advisable because of privacy issues. Where sample data is required for testing, you can create sample data in the development environment. Data in the development is retained when you update the environment.

If it is necessary to create a development environment with real user data, the recommended method is to create a mirror of the production system. The new environment is created by backing up the production database and restoring it as a development database.

To create a mirror of the production system, follow these instructions.

Development

Once you have created a development environment you can develop it and compile it without affecting the production system. For more information on how to develop Openbravo Basic Network, see the Developer's Manual

Creating a test environment

Once you have developed and tested code changes in the development environment, it is useful to test them in a separate test environment. To set up a test environment, make a mirror copy of the production system including its data by backing up the production system and backing it up to the test environment.

1. In the testing environment, execute the following commands:

   $ exp db_name/db_password@production_host file=/tmp/backup.dmp log=/tmp/backup.log owner=oracle_user statistics=none direct=yes consistent=yes
   

   $ imp db_name2/db_password2@localhost file=/tmp/backup.dmp log=/tmp/import.log fromuser=oracle_user touser=oracle_user2

2. To copy the database code from the development environment to the test environment, execute the following Ant commands in the development environment:

   $ ant export.database
   

   $ tar zcf /tmp/sources.tgz attachments/ build.xml config/ database/ legal/ lib/ log4j.lcf src src-core/ src-db/ src-trl/ src-wad/ web

3. In the test environment, execute the following commands:

   $ scp dev_user@dev_host:/tmp/sources.tgz /tmp
   

   $ cd /opt/AppsOpenbravo

   $ tar zxf /tmp/sources.tgz

4. If you are setting up the testing environment for the first time, manually edit the configuration files on the development environment. See Openbravo.properties article. Edit the following files:
   • config/Openbravo.properties.
   • config/log4.lcf

   In the configuration files, edit the following configuration information:

   • Database name (the SID).
   • Database IP address (or host name).
   • Database superuser password.
   • Openbravo database username and password.
5. Update, build and compile the database using the following Ant commands:

   $ ant update.database
   

   ant compile.complete

   ant war

6. Stop the Tomcat service.
7. Remove the old openbravo context.
8. Deploy the new openbravo.war.
9. Restart the Tomcat service. You can now access the testing environment using a web browser.

Updating the production environment

When code changes have been fully tested, update them on the production environment using the following process:

1. Translate the database into XML files by executing the following Ant command:

   $ ant export.database

2. In the development environment, execute the following command:

   $ tar zcf /tmp/sources.tgz  database src srcClient src-core src-db src-trl src-wad
   

   $ scp /tmp/sources.tgz openbravo@obnserver:/tmp

3. Make sure all users are disconnected from the production system.
4. In the production environment, execute the following commands:

   $ cd /opt/AppsOpenbravo
   

   $ tar zxf /tmp/sources.tgz

5. Update the database from the XML file using the following Ant command:

   $ ant update.database

6. Compile the build using the following Ant command:

   $ ant core.lib wad.lib trl.lib compile.complete war

7. Deploy the build to Tomcat:

   $ ant deploy

Reporting bugs and requesting support

To report a bug or raise a support ticket, visit http://support.openbravo.com and log in using the username and password supplied to you by Openbravo. If you have Openbravo ERP installed on multiple instances, it is recommended that you use the same account for all of those instances, so that you can see all the bugs you have raised in one place.