RPM - Introduction

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.


Introduction

Platform Independence

Adempiere is written in Java and as such strives to run on any operating system which is supported by Java. In effect it means that Adempiere can run on any modern operating system such as Windows, Mac OS X, Solaris, and Linux.

To install Adempiere, you download the binary package as zip-file from sourceforge, drop it somewhere into the directory tree, unzip the file, run RUN_setup.sh, and you have Adempiere installed and configured. The procedure is the same on any operating system.

While this platform independence is remarkable, it comes at a cost: The software can not be optimized for any particular system. Particularly on Linux machines, there are several issues which shall be examined in more detail.

Linux Issues

The Filesystem Hierarchy Standard

Linux follows the Filesystem Hierarchy Standard (FHS) which defines where what kind of files should be located.

According to the FHS, we would expect Adempiere to install its files in the following directories:

configuration files/etc/adempiere/
executable binaries/usr/bin/
libraries and resources/usr/lib/adempiere/
documentation/usr/share/doc/adempiere/
data and variable state files/var/lib/adempiere/
log files/var/log

But instead all files are just installed in one big chunk with its own sub-directory tree originating wherever you extracted the zip-file.

For such cases the FHS provides the /opt directory, where add-on packages may install all static files in their own subdirectory.1

Technically, even when using the /opt hierarchy, configuration files should actually still be located in /etc/opt/adempiere, and data and variable state files in /var/opt/adempiere. Executables should be placed in /opt/adempiere/bin. And a restriction exists that no files should exist outside the /opt, /var/opt, and /etc/opt hierarchies (except for those which must reside in specific locations to function properly).

But would strictly following the FHS standard really make sense?

Configuration Files

The rational for having all host-specific configuration files under a single directory is that users can easily predict their location. Hardcore Linux users much prefer tweaking settings in a configuration file by hand rather than being guided through a lengthy setup program.

But Adempiere does not expect anybody to modify its settings from outside and rather insists that RUN_setup.sh is used for that purpose. Programs under Linux expect that their configurations could have been changed any time, so they adjust themselves to the configured settings after those have been loaded and checked for sanity. Adempiere works the other way round: RUN_setup.sh checks the configuration parameters for sanity, adjusts all programs and libraries to the configured settings, and then saves those settings quasi as a saved-state file. When the programs are started, they load their last state from the configuration file and continue from there. Should you modify anything manually from outside of RUN_setup.sh, things will get seriously messed up.

In addition, the configuration files are all located near the executables and binaries where they are being used, which is not bad for testing and debugging.

Under these considerations, it probably makes sense to keep the configuration files where they are and not to move them to /etc/opt/adempiere.

But there is an issue with user-based configuration files for running the client, which are placed as visible files into the current working directory. These should be modified to be located in user's home directories as hidden files (filenames preceded with a .).

Executable Binaries

Having all executables in one directory makes it easy to include that directory in a user's path so that all commands for a particular package are always available.

In the case of Adempiere, there actually are no binaries but only Java classes which are called from shell scripts, and for ordinary users actually only one such script (RUN_Adempiere.sh) is required to start the client. And that would normally not be executed from a command line anyway, but rather from a menu on the desktop.

For administrators, although arguably it is sometimes difficult to understand why a particular script is to be found in ADEMPIERE_HOME, while another is in ADEMPIERE_HOME/utils, those are actually the only directories with interesting scripts to run. Furthermore, many of the scripts in the utils subdirectory actually require a certain structure of helper files and directory trees under them, which would be broken if they were to be moved to a separate bin directory.

Executables are thefore best left where they are.

Libraries and Resources

Libraries and resources are exactly the kind of files to be placed under /opt/adempiere, and the vendor is free to create any structure he wishes under his own subdirectory. So this is FHS compliant, and nothing needs to be changed.

Documentation

Adempiere mainly uses online documentation for users and a wiki for adminstrators and developers.

However, there is some documentation available in the source code which is not found in the binary distribution. Some of those files might be interesting for administrators or developers and should therefore be placed in /usr/share/doc/adempiere where they can easily be found.

Data and Variable State Files

Adempiere does not keep its own data files but rather stores all data in an external database such as Oracle or postgreSQL.

Log Files

Although the FHS states that no files should exist outside of the /opt, /var/opt, and /etc/opt hierarchies, it probably makes sense to cover log files with the files which must reside in specific locations to function properly exception.

Out of the box, Adempiere's log files are scattered over its subdirectories, often with duplicate and redundant information.

These log files can grow very big over time. If, as would be good practice, a separate partition is mounted on /opt/adempiere, that partion could easily get filled up with logs. It would be much better to use the operating system's logging facilities with all its advantages (for example, file rotation or remote logging) than clogging up the Adempiere partition.

Exceptional Files

Other files which would need to reside in specific locations to function properly would include

/etc/rc.d/init.d/adempiere

An init script to start and stop the application server.

/etc/sysconfig/adempiere

Configuration file for the init script.

/etc/profile.d/adempiere.sh

A short script to set the ADEMPIERE_HOME variable system-wide for all users.

/usr/share/applications/adempiere.desktop

A descriptive file to add a menu item for starting the client on the users' desktop.

/var/log/adempiere

As previously explained, a central log file used by the system logger to collect and manage all logs in one place.

Such files are very specific to RedHat-like systems and are not included in the vanilla Adempiere distribution.

Running as Daemon

The standard Adempiere distribution comes with the RUN_Server2.sh and RUN_Server2Stop.sh commands to start respectively stop the application server.2

The scripts are designed to run in the foreground dumping log information to the console from which they were started. The administrator is supposed to follow the state of the server by examinig the log messages on the console. Thus the server would be started on one console and left running, and to stop it a new console would need to be opened from which the stop command would be initiated. The administrator would then have to switch back to the original console to verify from the log messages that the server has really stopped.

While such procedure is acceptable for development purposes, it definitely does not scale well for production environments.

Apart from being impractical, under Linux another issue arises that the server would be running with the privileges and limitations of the user who started it, which could be any user or even root, raising very valid security concerns.

It would be much better to have a designated adempiere user for no other purpose than running the server, being able to start and stop the server with service adempiere start or service adempiere stop like any other daemon, and configuring startup and shutdown behavior with chkconfig.

Desktop Integration

Any user who wants to run the server or client must have the ADEMPIERE_HOME environment variable set to the correct location. That means ADEMPIERE_HOME should be set system-wide on both server and client machines.

And for users who want to run the client, having an item in their desktop menu is surely more comfortable than having to open a console and typing $ADEMPIERE_HOME/RUN_Adempiere.sh.

Package Management

On RedHat-like systems, software installation, upgrading, and uninstallation should be managed by RPM. This ensures consistent deployment and allows for centralized management of clients and servers.

How the Adempiere Source-RPM works

Preparation

The Adempiere source code is downloaded from the Mercurial repository at SourceForge.net, and file formats (end-of line difference between Windows and Linux) and file permissions (scripts should be executable) are corrected.

The standard building behavior is modified so that build results are not e-mailed to anybody, building stops after compilation and does not proceed to actual file installation, and generation of the distributable zip-file (the binary package which is distributed by Adempiere) is suppressed.

If required, some quick fixes are applied to solve known issues which need to be addressed before compiling.

Then a copy of the whole source tree is made. The idea is that two different products should be compiled, one from the pristine source which was downloaded, and one from a source containing additions and patches for customizations. Help and support will generally only be available for the original product, not for any extended or customized versions. By having an RPM with the pristine code available, problems can be replicated in the original product before filing support requests or bug reports.

Standard patches (those distributed with this Source-RPM) are applied.

After that, the packager has the opportunity to add his own sources and patches for customizations or local extensions or bugfixes. (Although it would of course be much nicer if the packager would contribute his bugfixes back to the Adempiere project instead of just silently applying them to his local copy).

Building

First the orginal source is compiled to build the pristine package.

Then the customized source is compiled to build the server subpackage.

Any pdf files found in the original or customized source after compilation are extracted as documentation files.

If requested, the server is "pre-configured". All parameters which would normally be set after installation when executing RUN_setup.sh can already be configured now, resulting in a server package which can run out of the box when it is installed on the target machine. This makes the administrator's life very easy, but of course it also means that the resulting RPM is location-specific and can not be distributed publicly.

The server is then configured to send its log messages to the system logger rather than using local files.

The client code is extracted from the server package and modified so that the user's properties file is a hidden file in his home directory.

As a last step, the documentation for the Source-RPM (this text!) is generated.

Packaging

The build results are installed in a root file system as they should appear on the target system when they get installed.

In addition to the compiled code, some support files are installed for additonal Linux-specific functionality:

A file is dropped into /etc/profile.d to set the ADEMPIERE_HOME environment variable on a system-wide level.

An init script and its configuration file are installed to allow starting up or shutting down or otherwise controlling the server with the service adempiere start or service adempiere stop or chkconfig adempiere commands.

A desktop file is dropped into /usr/share/applications to include the Adempiere client in the users' desktop menu.

Documentation files are placed into the /usr/share/doc directory.

RPM packages are built from this root filesystem (one for client, one for server, one for the pristine product), which can be distributed and installed on other machines.

Installation on the Target System

When the Adempiere packages are installed on the target machines, their behavior differs depending on the kind of package (client, server, pristine) and the type of installation (installation, upgrade, removal).

Installation

StepClientServerPristine
pre-install---create adempiere user---
create user home directory
configure rsyslog
installinstall files
post-installcreate ADEMPIERE_HOME symbolic link---
---autostart server on system boot---

Upgrade

StepClientServerPristine
pre-install---create adempiere user---
create user home directory
configure rsyslog
installinstall new files
post-installcreate ADEMPIERE_HOME symbolic link---
---autostart server on system boot---
pre-uninstall---
uninstallremove old files
post-uninstall---restart server---

Removal

StepClientServerPristine
pre-uninstall---stop server---
unconfigure autostart of server on system boot if no other server packages are installed
remove ADEMPIERE_HOME symbolic link if it points to this installation
uninstallremove old files
post-uninstallremove installation directory
unconfigure rsyslog if no more server installations exist
unconfigure system-wide setting of ADEMPIERE_HOME if no more server or client installations exist
remove desktop menu entry if no more server or client installations exist
remove ADEMPIERE_HOME symbolic link if no more server or client installations exist
remove user home directory and documentation if no other installations exist
create ADEMPIERE_HOME symbolic link to newest server or client if any server or client installations exist


[1] Which means that according to the FHS, Adempiere should always be installed in /opt/adempiere.

[2] The 2 is presumabely a remnant from the days before Adempiere

forked from Compiere, where these scripts where used to control the new version 2 server, as opposed to RUN_Server.sh and RUN_ServerStop.sh controlling

the old version 1 server, which has since been lost.