Openbravo SMB Network One Administrator's Manual 2.35
Introduction
This manual is intended for Openbravo Network system administrators. It describes the following tasks:
- Initial setup and operation of Openbravo Network.
- Installation, and initial configuration of the Openbravo SMB Network One software appliance.
- Typical maintenance and update operations such as scheduling backups, managing services, and applying patches.
- Managing custom code and performing disaster recovery from a backup.
- Migrating from any Openbravo ERP installation to Openbravo Network.
The document also includes recommended best practice for development using Openbravo Network.
This document is not a user manual or an implementation guide for Openbravo ERP. It will not explain how to use Openbravo ERP or describe any Openbravo ERP functionality.
Installation
There are two ways to install the Openbravo SMB Network One software appliance.
- Install the appliance to a dedicated server from an ISO DVD.
- Install the appliance to a virtual server from a virtual image.
Installing the software appliance from an ISO DVD
Before you begin, make sure that the BIOS of the server is configured to boot from the DVD drive, otherwise the installation process will not start. Consult the documentation for the motherboard to find out how to configure the BIOS.
Now follow these steps:
- Insert the DVD in the DVD drive.
- Reboot the system.
- For a standard installation, press Enter when prompted. If there are any problems with hardware detection, you may need to set up further parameters. To set up hardware parameters, use the following function keys:
- F2: Options
- F3: General
- F4: Kernel
- F5: Rescue
- Once you have set up the parameters correctly, the kernel loads.
- The installation wizard appears. Click Next.
- The license agreement appears. Scroll down to read the agreement.
- Click Next to accept the agreement and begin installing the appliance.
- From the Keyboard Configuration window, select the keyboard layout you require.
- Click Next. The Automatic Partitioning window appears.
- Choose from the following options:
- Remove all Linux partitions from this system. This option is recommended if you are replacing an already installed Linux system, but want to keep other partitions (for example a Windows partition).
- Remove all partitions from this system. This option is recommended if you are installing the appliance on a dedicated server.
- Keep all partitions and use existing free space. Select this option if you use an external tool for partitioning.
- To manually configure the partitions select the Review (and modify if needed) partitions checkbox and click Next. A separate window appears for you to specify the partition structure. To accept the default partitions without reviewing them, clear the checkbox and click Next.
- The Network Configuration window appears, showing a list of network devices that have been detected.
- To configure a device manually, select it and click Edit.
- If the device is allocated an IP address by DHCP, type DHCP in the box. Otherwise, specify the IP address. To make the device active at boot time, select the Active at boot time checkbox.
- Select Manual and type the hostname in the box.
- Click Next. The Timezone window appears.
- If your system clock is UTC (Universal Time Co-ordinated) select the System Clock is UTC checkbox. Otherwise, select the time zone you require from the list. You can enable UTC in the BIOS settings.
- Click Next. The installation process begins. Checking dependencies and installing the appliance can take up to an hour.
- When the installation is complete, remove the DVD from the DVD drive and reboot the system.
At this stage, you do not need to configure firewall and network services because they are configured using default parameters. You can make further adjustments using the Administration Console.
Installing the software appliance from a virtual image
You can install Openbravo Network using the following virtualization systems:
- VMWare
- VMWare ESX
- Citrix Xen
Before you begin, make sure that your system has a hypervisor that will support your chosen virtualization system. |
Now follow these steps:
Installation using VMWare or Citrix Xen
- Download and open the relevant virtual image you want to install.
- Configure the virtual image as follows. You can expand the available RAM memory to improve performance if the hardware has enough resources to do so.
- VMware image: 15GB of free space, 1.5GB of RAM, 512MB of swap space, bridged networking with DHCP.
- Citrix XenServer image: 15GB of free space, 512MB of swap memory.
- Start up the virtual machine, and wait until the initial compilation has taken place. This process takes approximately one hour.
Installation using VMWare ESX
If you are using VMWare ESX as your virtualization system, follow these steps:
- Choose or establish an ESX datastore from which the appliance image can be installed. For instructions on how to do this, consult the official VMware documentation.
- Unpack the compressed appliance image folder into the datastore. Verify that the folder contains all three files (two .vmdk files and one .vmx file).
- On the ESX server, select the Summary tab for the server where the datastore resides.
- Double-click the datastore name in the Datastore list.
- In the Datastore Browser, browse to the .vmx file.
- Right-click the vmx file and select Add to Inventory. The Add to Inventory Wizard starts.
- In the text box, type a name for the virtual machine.
- Click Next.
- Select a resource pool within which to run the virtual machine.
- Click Next.
- Review the selections on the Summary screen.
- Click Finish.
- Close the Datastore Browser if it is still open.
- Start the Virtual Machine.
System configuration
Once you have installed the Openbravo Network software appliance, you can use the web-based Administration Console to configure and manage the appliance, including rollbacks, updates and backups.
Accessing the Administration Console
- Launch your preferred Internet browser.
- Type https://ip_address:8003 (where ip_address is the system's IP address) into the address bar of your Internet browser. This IP address is displayed at the end of every boot process.
- The Administration Console appears.
- The Yourcompany logo which is displayed is a placeholder image. You can replace it with your company logo during the configuration process.
- Enter the administrator's username and password:
- User name: admin
- Password: password
- Click Sign In.
Using the Configuration Wizard
If you are accessing the Administration Console for the first time, the Configuration Wizard appears. The wizard only appears the first time you log in to the Administration Console. However, any settings you alter within the wizard can be changed later using the console.
Configuring users
For security, it is strongly recommended that you change the administrator's password immediately:
- Select Set Password.
- Enter the new password.
To set up other users with permission to access the Administration Console, follow these steps:
- Select Manage Users
- For each user you want to add, specify a username and password. The password must be at least six characters long.
Configuring e-mail
The Configuring e-mail window enables you to specify the address from which Openbravo Network will send system notifications, for example updates or backup notifications.
- Specify a mail relay host from which e-mails will be sent, for example localhost. A localhost mail relay server is installed with Openbravo Network. If there are multiple instances of Openbravo Network in your organisation, you can set up an address for instance, so that you can tell which address comes from which instance.
- Specify an address that Openbravo Network will use to send e-mails, for example obnetwork@mycompany.com. You can enter any valid e-mail address.
Configuring notifications
Specify the e-mail address or addresses to which Openbravo Network will send notification e-mails
Configuring networking
The Configure Networking window shows the network information you specified during the initial setup. To change any of the network settings, hover over the setting you want to change and click the Edit option when it appears.
Configuring a proxy server
To configure a proxy server, enter the configuration. If you do not have a proxy server, click OK to skip this step.
Scheduling backups
You can back up the Openbravo Network system automatically by scheduling backups in the Backup Configuration window. Specify when the backup will take place and where it will be stored.
Authentication
The final page of the configuration wizard requests the entitlement key which is supplied by Openbravo following the purchase of the appliance and enables you to receive system updates. Each entitlement key is unique to each system. The same entitlement key cannot be shared by several systems or malfunction may occur. If you do not have an entitlement key, contact Openbravo.
About the Administration Console
Once you have completed the initial configuration using the Configuration Wizard, you can access the Administration Console to change the configuration settings and manage the system. Select which setting you want to manage:
The Administration also gives you quick access to the following services:
- Openbravo Network Support
- Openbravo Services
Configuration menu
The configuration area of the Administration Console enables you to configure the following:
- E-mail. The e-mail settings are the same as the ones you completed using the Configuration Wizard.
- Networking. The network settings are the same as the ones you completed using the Configuration Wizard.
- Proxy server. The proxy server settings are the same as the ones you completed using the Configuration Wizard.
- Firewall.
- Configure Notifications. The notification settings are the same as the ones you completed using the Configuration Wizard.
- Time Zone and Time
- Upload SSL Certificate
- Users
- Entitlement key
- Update server
- Linux password
- Database
- Support password
Configuring the firewall
When you install Openbravo Network, the installation sets up a default set of iptables rules that are applied when you start the system. Openbravo Network's firewall uses the iptables Linux daemon. Visit http://www.netfilter.org/projects/iptables/index.html to find information about advanced firewall configuration. The following ports are open by default:
- SSH (port 22).
- http (port 80).
- https (port 443).
- Openbravo's Administration Console (port 8003).
To change the port configuration:
- Type the new configuration in the box. For example iptables -A INPUT -p tcp --dport PORT_NUMBER -j ACCEPT, where PORT_NUMBER is the port you want to open.
- Click save
Direct connection through a firewall
If the appliance administrator needs direct access to the database through the 1521 port, you must add an additional iptables rule:
- Access the Administration Console.
- From the menu, select Configuration > Configure Firewall
- Enter the following iptables rule:
- iptables -A INPUT -p tcp --dport 1521-j ACCEPT
- Click Save
Resetting the firewall
To reset the firewall to its default rules, follow these steps:
- Access the Administration Console.
- From the menu, select Configuration > Configure Firewall.
- Enter the following iptables rules:
- iptables -F
- iptables -X
- iptables -Z
- iptables --policy INPUT DROP
- iptables -A INPUT -i lo -j ACCEPT
- iptables -A INPUT -p icmp -j ACCEPT
- iptables -A INPUT -p tcp --dport 80 -j ACCEPT
- iptables -A INPUT -p tcp --dport 22 -j ACCEPT
- iptables -A INPUT -p tcp --dport 443 -j ACCEPT
- iptables -A INPUT -p tcp --dport 8003 -j ACCEPT
- iptables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
- Click Save.
Configuring the time and time zone
Changes to the date and time could result in unexpected behavior such as service timeouts. |
To update only the timezone:
- Select Set Timezone Only.
- Select the timezone you require.
To adjust the time and date manually:
- Clear the Synchronize clock with Internet servers checkbox.
- Select the timezone and time you require from the drop-down list.
To use a network time protocol (NTP) server to set the time:
- Check the Synchronize clock with Internet servers checkbox. The drop down lists for selecting the time and time zone become unavailable.
- Type the DNS hostname or IP address of the NTP server in the text box.
- Click Save.
When you have set the time and time zone, click Proceed to continue, or Cancel to make further changes.
Uploading an SSL certificate
By default, Openbravo SMB Network has a self-generated SSL certificate. If you have an external certificate (for example from Verisign), you can upload it:
- Click Browse.
- Navigate to the SSL certificate file. SSL certificate files have the .pem extension.
- Click OK to begin uploading the certificate. It will be used by both Openbravo ERP and the Openbravo SMB Network Administration Console.
Configuring users
The Users area sets up other administrators to use the Administration Console specifies which tasks they are allowed to perform.
To add a user:
- Select the Manage Users tab.
- Select Click to Add Another Item.
- In the Admin Password box, enter the password for the Admin account.
- Type the user name of the new users.
- Type and confirm the password for the new user.
- By default the new user is added to the admin group. No other groups are available.
- Click Add. The new users is added to the list.
To change the password on the Admin account:
- Select the Set Password tab.
- Type the current password and new password in the text boxes provided.
- Click Change Password.
- Click X to dismiss the confirmation dialog box.
Adding an entitlement key
To receive updates from Openbravo, you must enter an entitlement key. If you have not already entered an entitlement key using the configuration wizard, type it in the box.
Update server
The Update Server window controls the delivery of updates. Do not change these settings unless you are asked to do so by the Openbravo support team.
Configuring the Linux password
Linux users can access Openbravo Network using the Secure Shell protocol (SSH) via a terminal. To access the system in this way, an additional password is required. The default username / password is:
- username: openbravo
- password: openbravo
Note that there is no root SSH access in Openbravo SMB One software appliance. To perform administration functions, use either the Administration console or SSH and a terminal.
To change the Linux password
- Type the new Linux password in the box.
- Confirm the password.
- Click OK.
Database configuration
Use the Database Configuration window to change the system password of the database, and the language. To change the system password of the database:
- Select the Database Password tab.
- Type the new password in the box. The password must not begin with a numeric character.
- Click OK.
To change the language of the database:
- Select the NLS_Lang tab.
- Select the language you require from the list.
- Click OK.
Support password
You can access the Openbravo Support Portal directly from the Administration Console, to raise a bug or make a second-level support request, or to view support issues already raised. The User Id and Password for the Bug Support portal are supplied when you first purchase Openbravo Network.
- Select the Bug Support tab.
- Type the User ID and Password supplied by Openbravo.
- Click OK.
If your Bug Support issue does not relate to a bug report, or the installation or operation of Openbravo Network, your support request will be rejected. |
The User Id and Password for the 2nd Level Support portal are supplied when you purchase a 2nd Level Support service.
- Select the 2nd Level Support tab.
- Type the User ID and Password supplied by Openbravo.
- Click OK.
Support issues logged in the the 2nd Level Support portal will be charged, as specified in your 2nd Level Support contract. |
Using the same User Id allows to have a common view of the issues reported in different Openbravo SMB Network systems. The Openbravo Support Portal can also be accessed at support.openbravo.com
Maintenance
The Maintenance menu contains the following options:
System services
Use the System services page to start, stop and restart the following services:
- Tomcat
- Apache httpd
- SSH
- The iptables firewall
- Oracle
You can also schedule restarts for each service at a particular time:
- Click the calendar icon next to the service for which you want to schedule a restart.
- Specify the date and time that the service will restart.
- Click Save. The time and date of the restart appears underneath the service.
To cancel a scheduled restart:
- Click the calendar icon next to the service for which the restart is scheduled.
- Click the date that the restart is due to take place.
- Click Remove. The restart is removed from the list.
System logs
You can view the following Openbravo, Tomcat and Apache httpd logs from the Administration Console:
- Openbravo ERP log: log4j_TAD.log.
- Openbravo compilation log.
- Openbravo update conflicts log.
- Tomcat log: catalina.out.
- Apache httpd access log.
- Apache httpd error log.
To view a log:
- Select System Logs.
- From the drop-down menu, select the log file you require.
- Click Download to obtain the whole log file.
Backup and restore
The Backup and restore window enables you to launch a manual backup of Openbravo Network, schedule regular backups, or restore the system from a backup.
Backing up Openbravo Network
To configure backups and set the backup schedule:
- Select the Backup Configuration tab
- From the Enable Backup Schedule option, click Yes.
- Select how often you want the schedule to take place. You can choose to schedule backups daily, weekly or monthly.
- If you have selected weekly backups specify which day of the week the backups will take place. If you have selected monthly backups, specify which day of the month the backups will take place.
- Specify the time of day that the backup will take place.
- In the Number of Backups box, type the maximum number of backups that will be stored at any one time.
- From the Backup Type list, select the format of the backup. You can select a Mounted File System, or select one of the following remote shares:
- Network File System Share (NFS).
- Windows(R) File System Share (CIFS or SMB).
- If you selected Mounted File System, label the disc by typing in the Disc Label box.
- In the Connection Host box, type the IP address or host name and the shared resource name, for example 192.168.1.100/backups. You do not need to type // before the IP address.
- Specify the connection path. For remote shares (NFS, CIFS, and SMB), this is the full path on the share where the backup should be stored. For mounted filesystems, this is the path relative to the mountpoint where the backups are to be stored.
- For remote shares, specify a username and password to connect to the connection host, if required.
- Click Save.
 | Do not, under any circumstances, do a backup in the same partition where Openbravo SMB Network is installed! |
Once you have set up the backup location you can also back up Openbravo SMB Network One at any time using the manual backup button:
- Select the Backups tab.
- Select Backup Now.
Backing up the system manually does not affect the normal backup schedule. You must set up the backup location in the Backup Configuration tab before performing a manual backup.
To keep informed of tasks that are due to take place without logging into the Administration console, subscribe to the Schedule RSS Feeds |
Restoring Openbravo Network from a backup
To restore Openbravo Network from a backup, follow these steps:
- Select the Backup and Restore menu option.
- Select the Backup tab.
- Select the backup file you want to restore.
- Click Restore.
- Click OK. When the restoration is complete, the Openbravo Network software applicance is restarted and a notification is sent to the administrator.
Schedule reboot
Use the Schedule Reboot page to reboot the Administration Console, Schedule a reboot or close down the Administration Console.
To reboot the Administration Console:
- Click Reboot.
- Click Yes to confirm your choice.
To shut down the Administration Console:
- Click Shutdown.
- Click Yes to confirm your choice.
To schedule a reboot of the Administration Console:
- Click Schedule.
- Use the calendar to specify a date and time for the appliance to reboot.
To cancel a scheduled reboot:
- Select Schedule.
- Using the calendar, navigate to the date that the reboot is due to take place.
- Click Remove. The scheduled reboot is removed from the list.
Disaster recovery
In the event of a disaster, complete the recovery process as follows:
- Reinstall the Openbravo Network appliance.
- Access and log onto the Openbravo Network administration console.
- Select Management > Backup and Restore.
- Specify the location of the existing backups.
- Enable backup scheduling. This is necessary to enable a scan for existing backups.
- In the Backup tab, choose the backup file from which to restore. Click Restore beside the desired backup in the list.
- Click OK. When the restoration process is finished, the system will restart and a notification e-mail is sent to the administrator.
Updates
The Update menu contains the following options:
- System Updates
- Compile and deploy
- Manage Rollbacks
System updates
Use the System Updates window to check for and install updates. After installing an update, Openbravo ERP launches a compilation process automatically. Therefore there is no need to launch a manual compilation after an update.
Before applying any update, request that all Openbravo ERP users log out. Make sure you give users enough notice time to complete their transactions.
To check for updates:
- Select Updates > System Updates from the menu.
- Select Check Now.
- A list of available updates appears in the window. If there are no available updates, a message appears saying that no updates are available.
- Click the pyramid icon to expand the list of updates.
- To install the update, click Apply Now to begin installing the update.
- To schedule the update for installation at a later date, select Schedule and specify the time and date when you want the update to be installed.
You can also set up recurrent checks for updates that take place on the time and date of your choosing.
Scheduled checks for updates are performed at a random time between the hour selected and the next hour. The precise hour and minute of the check is displayed on the Updates window. |
To schedule a recurrent check for updates:
- Select Updates > System Updates from the menu.
- Select the Preferences tab.
- To enable scheduled updating, select the Check for updates checkbox.
- Choose from the drop-down list whether you want to check for updates daily, weekly or monthly.
- For daily updates, specify the time of day that the update will take place.
- For weekly updates, specify the day of the week and the time that the update will take place.
- For monthly updates, specify the day of the month and the time that the update will take place.
- To automatically install any updates, select the Automatically Install Updates checkbox. Clear the checkbox if you want to only be notified when updates are available. It is recommended that you do not install updates automatically, in case the installation takes place while users are operating the system; installing updates while the system is in use can lead to database inconsistencies.
- Click Save.
You can also subscribe to the RSS Feeds to receive notifications when updates are available, and when updates you have scheduled are due to take place |
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:
Source code conflicts
If an update from Openbravo includes changes to a line of code that you have customized, a source code conflice may occur. When the update process is complete, a message appears which either notifies you that the update was successful, or notifies you that there are conflicts that need resolving. You may encounter the following messages:
- Update and Openbravo compilation processes completed. This message means that the installation, merge, compilation and deployment of the update was successful. To confirm that the update was successful, select Management > System Logs and check the Openbravo Compilation Log and the Openbravo source code conflicts Log files.
- Source code conflicts. Solve the conflicts and launch a compilation: This message means that a conflict occured during the code merge process. In this situation the compilation process is not launched and Openbravo Network will remain at the previous version until the conflict is resolved.
To resolve the conflict and complete the update, follow these steps:
- From the menu, select Management > System Logs. The system log shows all the files with conflicts. The original files are kept untouched, and there is a corresponding .conflicts file. If for example there is a conflict in LoginUtils.java, it will remain unchanged. The conflicts file (in this example LoginUtils.java.conflicts) describes the conflicts file using standard diff syntax.
- To resolve the conflicts, transfer the /opt/AppsOpenbravo/merge_conficts.tar.gz file to the development environment.
- Resolve the conflicts. For example if there was a conflict in the DeleteClient.java file, the DeleteClient.java.conflicts file would look like this:
-
@@ -83,7 +83,8 @@
- if (myMessage==null) {
- myMessage = new OBError();
- myMessage.setType("Success");
- - myMessage.setTitle("");
- + myMessage.setTitle("Sucess");
- + myMessage.setDescription("Succesful process");
- myMessage.setMessage(Utility.messageBD(this, "Success", #:vars.getLanguage()));
- }
- -83,7 means that the conflict starts in the line number 83 and that a chunk of 7 lines of the original file is shown.
- +83,8 represents the additions by the update and means that the 8 line chunk of code starts in line 83.
- The lines starting with a minus symbol(-) are the lines from the existing
-
> version. The lines starting with a plus symbol(+) are the lines from the > Openbravo update. Lines without any preceding symbol are common to both > files.
- Decide which changes to keep, and edit the .java file accordingly.
- Transfer a tarball of the correct files (without the .conflicts files) from the development machine to the /opt/AppsOpenbravo directory of Openbravo Network.
- Extract the files from the tarball into /opt/AppsOpenbravo.
- To update the database with the updated changes select Update > Compile and Deploy from the menu.
- Select Database Update. Check the compilation logs for the results.
- From the menu, select Update > Compile and Deploy.
- From the Target menu, select Compile the whole application. Check the compilation logs for the results.
After the update has been completed, log into Openbravo ERP to verify that the system is running properly. If the update cannot be completed successfully, restore the system.
Compile and deploy
You can compile an specific window, the whole application or a customized task. After the window, task or application is compiled, it is automatically deployed. Check the compilation logs in the System Logs menu entry for the compilation results.
To compile a window:
- Select Update > Compile and deploy.
- From the Target menu, select Compile Window(s).
- In the Options box, type the name of the window you want to compile. You can enter more than one window.
- Click Compile. The window is compiled and deployed automatically.
To compile the whole system:
- Select Update > Compile and deploy.
- From the Target menu select Compile the whole application.
- Click Compile.
To compile a custom task:
- Select Update > Compile and deploy.
- From the Target menu, select Custom task.
- In the Options box, enter a custom Ant command. For example, to run ant compile -Dtab=xx translate, enter compile -Dtab=xx translate.
Manage rollbacks
Use the Manage rollbacks window to reverse updates that have been applied to the system.
The packages shown in a single rollback entry only apply to that entry. Expand all newer rollback entries to view the list of all packages that would be affected if the system were rolled back to that point. |
To roll back Openbravo Network to a previous point, follow these steps:
- Select Update > Manage Rollbacks.
- Scroll through the list of rollbacks to view the rollback identifier and time stamps.
- Select a rollback from the list to roll back all changes during and after that update.
- Click the arrow next to a rollback entry to expand the entry and view the packages affected by the update performed at that time.
- Click Do Rollback to apply the rollback, reversing all updates to the system during and after that point.
- Click OK to confirm the rollback.
RSS Feed
The Administration Console has an RSS feed which can inform you automatically when updates are available, or when scheduled tasks are due. There are two feeds that you can subscribe to:
- Schedule: the Schedule feed lists any tasks that you have scheduled to take place in the future, for example updates, scheduled reboots or backups.
- Updates: the updates feed notifies you when updates are available.
To subscribe to an RSS feed:
- The RSS feed links are on the top right corner of each window in the Administration Console. Click on the feed you want to subscribe to. The subscription window appears.
- Select the reader you want to use for the RSS feed. You can choose from the following:
- Live Bookmarks
- Microsoft Outlook
- Bloglines
- My Yahoo
- Alternatively, select Choose Application to browse to the RSS reader of your choice.
The
Uploading custom code files
This section explains how to upload custom code created in an Openbravo Development Environment to the Openbravo Network software appliance.
To copy the custom files onto the Openbravo Network appliance, you will need a Secure FTP (SFTP) client. SFTP uses SSH to transfer files securely and you can use it either with a GUI or a command line interface.
Some well-known SFTP clients are:
- Linux: Nautilus, Konqueror, gftp, lftp, sftp.
- Mac: Cyberduck, Fugu, lftp, sftp.
- Windows: WinSCP, Filezilla, psftp
Before you begin uploading custom code all users must be logged out, otherwise severe system malfunction or database inconsistencies can occur. |
When you are ready to begin uploading, follow these steps:
- Start your preferred SFTP client.
- Connect to the Openbravo appliance using the following information:
- IP address: the same as the one used in the Openbravo web URL.
- Username: openbravo.
- Password: the openbravo user password.
Once connected, copy the custom files to /opt/AppsOpenbravo/srcClient.
Developer guidelines
Openbravo SMB Network One comprises a single Openbravo environment, which is intended for production. It does not provide alternative environments for development and testing purposes. This section describes best practices for development and testing by creating 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 live environment while users are logged in, although it is safe to perform basic configuration tasks such as defining document types, roles and clients. Because of that, 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 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 instructions that follow assume a basic familiarity with Openbravo ERP, Openbravo SMB Network One and their operations. For help with installing and managing Openbravo SMB Network One, consult the instructions at the start of this manual. Command line instructions are examples only and may not be accurate in all installations. Each environment may need different commands or options. |
Development on Multiple Environments
If you are already running Openbravo SMB Network One in the production environment but want to change system behaviour, new development may be required. For example, you may require a new window or want to modify an existing 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.
The development environment does not need to be a mirror of the production environment and it does not need an Openbravo Network 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. Openbravo Network uses Oracle rather than PostgreSQL. Refer to Oracle's own documentation to install it on Linux or on Windows. 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 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 Network and restoring it to a new environment. This method will export the user data as well as the system itself. This method 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-5 show the development processes taking place:
- Creating and updating the development environment: sources and the database of Openbravo ERP are copied from the production environment to a development environment. This means that development can take place without disrupting the production environment.
- Development: changes are coded and tested in the development environment.
- 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.
- Deployment: when the changes pass testing, they are copied from the development environment to production environment.
- Update: the Openbravo Network stack is updated. Local development is preserved and any possible conflict is resolved as a new development.
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, 4 and 5.
- Production, development and testing environments (red). This is the recommended best practice for sophisticated development. All five 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:
- In the production environment, execute the ant export.database command. 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).
- 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
- 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
- In the development environment, execute the following commands:
- $ scp openbravo@obnserver:/tmp/sources.tgz /tmp
- $ mkdir AppsOpenbravo
- $ cd AppsOpenbravo
- $ tar zxf /tmp/sources.tgz
- Manually edit the configuration files on the development environment. See Configuring Openbravo Manually. Edit the following files:
- config/Openbravo.properties.
- config/XmlPool.xml
- config/dbCon5.xml
- 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.
- Create the database and compile it using the the following commands:
- ant create.database
- ant core.lib wad.lib trl.lib compile.complete.development
- In the development environment, restart the Tomcat service. You can now access Openbravo Network 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:
- 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
- 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/
- In the development environment, execute the following commands:
- $ scp openbravo@obnserver:/tmp/sources.tgz /tmp
- $ cd /opt/AppsOpenbravo
- $ tar zxf /tmp/sources.tgz
- Update and compile the database using the following ant commands:
- ant update.database
- ant core.lib wad.lib trl.lib compile.complete.development
- In the development environment, restart the Tomcat service. You can then access Openbravo Network via a web browser.
Copying user data to the development 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, 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
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 Network, see the Developer's Guide
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.
- 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
- 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
- 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
- If you are setting up the testing environment for the first time, manually edit the configuration files on the development environment. See Configuring Openbravo Manually. Edit the following files:
- config/Openbravo.properties.
- config/XmlPool.xml
- config/dbCon5.xml
- 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.
- Update, build and compile the database using the following ant commands:
- ant update.database
- ant compile.complete
- ant war
- Stop the Tomcat service.
- Remove the old openbravo context.
- Deploy the new openbravo.war.
- 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:
- Translate the database into XML files by executing the following ant command:
- ant export.database
- 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
- Make sure all users are disconnected from the production system.
- In the production environment, execute the following commands:
- <tt>$ cd /opt/AppsOpenbravo
- $ tar zxf /tmp/sources.tgz
- Update the database from the XML file using the following ant command:
- ant update.database
- Access the Administrative Console.
- From the menu, select Compile and Deploy
- Access the updated production environment using a web browser.
Updating Openbravo Network
If your installation of Openbravo Network has not undergone any further development, updates from Openbravo are installed .
If the user's system contains custom developments, however, conflicts may arise when applying the Openbravo ERP components of a system update. This is because the custom developments might have changed some source elements that have also been changed in the product update.
If there is a conflict, the process stops after having applied the changes to the source code but before compiling the system. Because of that, the production system is not affected and can be re-opened to end users while the conflicts are being resolved. End users will not see the effects of the new update but they can resume working as before.
- Update the development environment.
- Resolve the conflict in the development environment.
- Promote the resolved conflict to the production environment.
See System updates for more information about the conflict resolution procedure.
Migrating from Openbravo ERP to Openbravo Network
This section explains how to migrate from a Openbravo ERP (Oracle) installation (deployed from either the community installer or built from sources using Subversion), to a Openbravo Network installation.
If you are running a community installation using PostgreSQL, see the instructions on the wiki describing how to migrate to Oracle.
Before you begin, collect the following network configuration information:
- IP address in case of having a static IP.
- Hostname.
- Gateway.
- DNS servers.
Now follow these steps:
- Export the database to a dump file and save it on another computer or on an external USB drive. For example, if TAD is the schema owner the command would be:
- $ exp TAD/TAD file=openbravo.dmp log=openbravo.txt owner=TAD consistent=Y statistics=none
- Save the following directories on another computer or on an external USB drive:
- src-core
- src-trl
- src-wad
- web
- src
- srcClient
- database
- Make a full system backup.
- Install Openbravo Network onto a computer following the instructions provided in this manual.
- Copy the dump file created in step 1 to the Openbravo Network machine, for example to the /tmp folder.
- Save the following files in another directory outside of the /opt directory. The database directory will be replaced and it will need to restore these files later:
- /opt/AppsOpenbravo/build.xml
- /opt/AppsOpenbravo/database/build.xml
- /opt/AppsOpenbravo/database/scriptComplete.sh
- /opt/AppsOpenbravo/database/scriptRecompile.sh
- /opt/AppsOpenbravo/database/scriptLevel.sh
- Delete the following directories from the Openbravo Network machine:
- src-core
- src-trl
- src-wad
- web
- src
- srcClient
- database
- srcAd
- build
- In the Administration Console, stop the Tomcat service.
- Delete the TAD user, using the following command:
- :$ sqlplus system/sa
drop user tad cascade;
- Create a new database user. The user name must be TAD to avoid changing the configuration files.
- $ sqlplus system/sa
create user tad identified by tad default tablespace users temporary tablespace temp;
- Grant DBA priviledges to the TAD user:
- $ sqlplus system/sa grant dba to tad;
- Import the dump that you copied to the /tmp directory in step 5:
- $ imp tad/tad file=/tmp/openbravo.dmp log=/tmp/openbravo.log fromuser=tad touser=tad
- If the database owner in the original installation was not called tad, modify the fromuser option.
- Copy the files you saved in the step 2 to the Openbravo Network machine, in the /opt/AppsOpenbravo directory.
- Access the Administration Console
- From the menu select Backup and restore.
- Restore the system.
- From the menu, select Update > Compile and deploy.
- From the Target menu, select Compile the whole application.
- Click Compile
After 10-40 minutes (depending on the hardware), Openbravo ERP will be ready to use and migrated to Openbravo Network.
Select Maintenance > System logs and check the system log to verify that the deployment is complete.
Appendix
Direct database connection
Openbravo Network allows you to connect to the Oracle database though a SSH tunnel and using the Oracle client of your choice. For security reasons it is not possible to access the database port directly.
Connecting to the database (Linux / Mac / BSD)
Use the following steps to connect to Oracle in Linux, Mac or any other Unix-like operating system:
- Open a command-line terminal and type the following command, replacing 'obnetwork' with the correct IP address.:
- ssh -N -L 1522:localhost:1521 openbravo@obnetwork
- This forwards the Openbravo Network's 1521 Oracle port into the 1522 port of the user's local client machine, tunneled over a SSH connection
- Type the openbravo user's password and leave this terminal opened.
- Open the Oracle client and specify the following connection settings:
- Host: localhost
- Port: 1522
- SID: onorcl
The connection will be available as long as the previous terminal is open.
Connecting to the database (Windows)
Use PuTTY to connect to Oracle in Windows. PuTTY is an open source and free SSH client:
- Select Session
- In the Host Name box, enter IP Address of the Openbravo Network machine.
- Select Connection>SSH>Tunnels.
- In the Source port field, enter 1522.
- Click Add.
- Click Open to open the ssh connection.
- Type the openbravo user name and its password and leave this terminal opened.
Certified hardware
A list of hardware components that have been successfully tested with the Linux kernel included in Openbravo Network is available on the Openbravo Website
Category: Professional Edition ERP