RPM - Introduction
Contents
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_HOMEvariable 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
| Step | Client | Server | Pristine |
|---|---|---|---|
| pre-install | --- | create adempiere user | --- |
| create user home directory | |||
| configure rsyslog | |||
| install | install files | ||
| post-install | create ADEMPIERE_HOME symbolic link | --- | |
| --- | autostart server on system boot | --- | |
Upgrade
| Step | Client | Server | Pristine |
|---|---|---|---|
| pre-install | --- | create adempiere user | --- |
| create user home directory | |||
| configure rsyslog | |||
| install | install new files | ||
| post-install | create ADEMPIERE_HOME symbolic link | --- | |
| --- | autostart server on system boot | --- | |
| pre-uninstall | --- | ||
| uninstall | remove old files | ||
| post-uninstall | --- | restart server | --- |
Removal
| Step | Client | Server | Pristine |
|---|---|---|---|
| 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 | |||
| uninstall | remove old files | ||
| post-uninstall | remove 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.