|
|
| (22 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | <b><big>RPM User Manual</big></b><br><b>Adempiere RPM Packager</b><br>by <span class="firstname">Stefan</span> <span class="surname">Christians</span><br>2011-08-02
| + | #REDIRECT [[RPM]] |
| − | | + | |
| − | <small><i>This program is part of Adempiere ERP Bazaar<br>http://www.adempiere.org
| + | |
| − | | + | |
| − | Copyright © Stefan Christians
| + | |
| − | <br>Copyright © Contributors
| + | |
| − | | + | |
| − | This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.<br>This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.<br>You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
| + | |
| − | | + | |
| − | Contributors: <span class="personname"><span class="firstname">Stefan</span> <span class="surname">Christians</span></span>
| + | |
| − | <br>Sponsors: K.K. Alice
| + | |
| − | | + | |
| − | Adempiere is a registered trademark of Adempiere, Inc.<br>All other company or product names are mentioned for identification purposes only, and may be trademarks of their respective owners.</i></small>
| + | |
| − | | + | |
| − | | + | |
| − | <div class="abstract" title="Packaging and Distributing Adempiere on RedHat-like Systems"><p class="title"><b>Packaging and Distributing Adempiere on RedHat-like Systems</b></p><p>This source package includes the Spec File and tools to download, customize, compile, configure, distribute, install, and run Adempiere on RedHat-like systems which use RPM as their package manager.</p></div>
| + | |
| − | ----
| + | |
| − | =Preface=
| + | |
| − | <div><div class="titlepage"><div><div></div></div></div><p>The Spec File to build the Adempiere RPM was developed and tested on Fedora 13.</p><p>The Fedora Packaging Guidelines have been followed, with some exceptions:</p><p>
| + | |
| − | ;Version and Release Numbering :Version information should be in the form: majorVersion.minorVersion-buildNumber.patchNumber[.releaseTag] So if upstream releases its product as adempiere351a, it should be packaged as: adempiere-3.5-1.X.a (where 1 is the build number and X is the packager's "patch level", which is incremented on each build).However, upstream maintains the build number as part of the version number, and it does not follow the convention of 0=pre-release, 1=release, >1=post-release. For RPM's version control method, it therefore makes more sense to use the revision in the Mercurial repository as build number.We also want to have automatic patch-level numbering, and the build date seems most suitable for that purpose.Therefore, our version numbering will have following syntax: majorVersion.minorVersion.buildNumber-hgRevision.buildDate[.releaseTag] which would result in following package names: adempiere331 -> adempiere-3.3.1-1943.buildDate adempiere354a -> adempiere-3.5.4-5276.buildDate.a adempiere360lts -> adempiere-3.6.0-6510.buildDate.lts
| + | |
| − | ;Pre-built Binaries and Libraries :All binaries and libraries in Fedora packages must be built from source code. The source package is not allowed to contain pre-built binaries and libraries.However, Adempiere comes with various *.jar archives containing pre-built *.class files.Some of them are simply used as tools in the build-chain and would easily be replaceable with open-source Fedora libraries.Others are used in the final product such as the jdbc-drivers for database connections. They would be more difficult to replace, although it would certainly be possible.Since we are going to build Adempiere packages for our own use and not for distribution with Fedora, we will gracefully ignore this requirement for the time being. ; Spec File Legibility :All efforts have been made to keep the Spec File legible, whereby priority has been given to legibility in terms of humanly readable over being able to read and understand the algorithms.Normally the user would only have to set or modify parameters at the beginning of the file (marked “SETTINGS”), add his sources and patches to the preamble (marked “your custom sources come here” and “your custom patches come here”), and install or apply them in the %prep section (marked “install your sources here” and “apply your patches here”). Everything else should just work.Many different parameters can be used in the Spec File, and commenting them all in place would result in a very long settings section where important or conflicting parameters could easily be overlooked. Instead, the parameters are explained with their default values in the appendix of this manual. All parameters have sensible default values, so even if no parameters are set the Spec File will still produce an installable and runnable package.Macros used by the build and installation scripts are defined and evaluated in a section titled “INITIALIZATION”, which comes between the settings and the preamble. Inside the scripts, the function and contents of those macros can be understood intuitively by their names, and as most people will not want to get into the detailed algorithms of how they were defined, the definitions are written in a way that keeps the Spec File nice and tidy and easily readable by humans. For debugging purposes, it is recommendable to expand those macros to multiple lines where necessary for easier understanding of conditions, loops, etc.A lot of regular expressions are used in combination with grep, sed, and awk in the macro definitions. They are not further explained, as commenting one line of code with twenty lines of explanation would make the Spec File difficult to read as a whole.Since all sub packages use exactly the same installation scripts (behavior is tweaked for each sub package by just setting some variables at the beginning of the scripts), rather than writing the scripts again and again, they have been included as source files which will be dynamically expanded when the packages are built.The SOURCES directory easily becomes very messy when numerous source files and patches are scattered about. For this reason, the files distributed with the Source-RPM are prefixed with sXXX_ (for sources) and pXXX_ (for patches), where XXX corresponds to the patch or source number in the Spec File. Users are encouraged to name their sources and patches following the same scheme, starting with number 100. ; Tags :The Packager and Vendor tags are used in spite of the guideline's recommendation not to do so. They are used for identification and documentation purposes to differentiate between the original distribution and patched versions.The BuildRoot tag is present for compatibility with other RedHat-like systems. ; Requirements :Adempiere requires Java to run. As of Adempiere 3.6.0, JDK 1.6 is required.Actually any Java distribution can be used, and the original Sun Java software is most tested and reliable for Adempiere. But since it is not distributed as an RPM, and theoretically can be installed at any location, it is virtually impossible to check for it as a build or target requirement.Therefore the openJDK distribution is listed as requirement for both compiling the source and installing the RPM on a target machine. The user is still free to use any Java distribution he wants, but openJDK must at least be installed. ; Documentation :Adempiere mainly uses online documentation. Text files such as README in the source code are often meaningless. However, all pdf files found in the source after compiling are copied into the documentation folder for all sub packages, regardless in which sub package they were found and without distinguishing whether they are for users, administrators or developers. ; Users and Groups :If the adempiere user or group already exists on the target system, an attempt is made to change the uid and gid to those defined in the Spec File, and to move the home directory to the location defined in the Spec File.</p></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Introduction=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Platform Independence==
| + | |
| − | </div></div></div><p>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.</p><p>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.</p><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Linux Issues==
| + | |
| − | </div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===The Filesystem Hierarchy Standard===
| + | |
| − | </div></div></div><p>Linux follows the Filesystem Hierarchy Standard (FHS) which defines where what kind of files should be located.</p><p>According to the FHS, we would expect Adempiere to install its files in the following directories:</p><div class="informaltable"><table border="0"><tr><td align="left">configuration files</td><td align="left"><code class="filename">/etc/adempiere/</code></td></tr><tr><td align="left">executable binaries</td><td align="left"><code class="filename">/usr/bin/</code></td></tr><tr><td align="left">libraries and resources</td><td align="left"><code class="filename">/usr/lib/adempiere/</code></td></tr><tr><td align="left">documentation</td><td align="left"><code class="filename">/usr/share/doc/adempiere/</code></td></tr><tr><td align="left">data and variable state files</td><td align="left"><code class="filename">/var/lib/adempiere/</code></td></tr><tr><td align="left">log files</td><td align="left"><code class="filename">/var/log</code></td></tr></table></div><p>But instead all files are just installed in one big chunk with its own sub-directory tree originating wherever you extracted the zip-file.</p><p>For such cases the FHS provides the /opt directory, where add-on packages may install all static files in their own subdirectory.[[#ftn.id2601867|1]]</p><p>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).</p><p>But would strictly following the FHS standard really make sense?</p><div><div class="titlepage"><div><div>
| + | |
| − | ====Configuration Files====
| + | |
| − | </div></div></div><p>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.</p><p>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.</p><p>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.</p><p>Under these considerations, it probably makes sense to keep the configuration files where they are and not to move them to /etc/opt/adempiere.</p><p>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 .).</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Executable Binaries====
| + | |
| − | </div></div></div><p>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.</p><p>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.</p><p>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.</p><p>Executables are thefore best left where they are.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Libraries and Resources====
| + | |
| − | </div></div></div><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Documentation====
| + | |
| − | </div></div></div><p>Adempiere mainly uses online documentation for users and a wiki for adminstrators and developers.</p><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Data and Variable State Files====
| + | |
| − | </div></div></div><p>Adempiere does not keep its own data files but rather stores all data in an external database such as Oracle or postgreSQL.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Log Files====
| + | |
| − | </div></div></div><p>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.</p><p>Out of the box, Adempiere's log files are scattered over its subdirectories, often with duplicate and redundant information.</p><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Exceptional Files====
| + | |
| − | </div></div></div><p>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.</p><p>Such files are very specific to RedHat-like systems and are not included in the vanilla Adempiere distribution.</p></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Running as Daemon===
| + | |
| − | </div></div></div><p>The standard Adempiere distribution comes with the RUN_Server2.sh and RUN_Server2Stop.sh commands to start respectively stop the application server.[[#ftn.id2602316|2]]</p><p>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.</p><p>While such procedure is acceptable for development purposes, it definitely does not scale well for production environments.</p><p>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.</p><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Desktop Integration===
| + | |
| − | </div></div></div><p>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.</p><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Package Management===
| + | |
| − | </div></div></div><p>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.</p></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==How the Adempiere Source-RPM works==
| + | |
| − | </div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Preparation===
| + | |
| − | </div></div></div><p>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.</p><p>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.</p><p>If required, some quick fixes are applied to solve known issues which need to be addressed before compiling.</p><p>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.</p><p>Standard patches (those distributed with this Source-RPM) are applied.</p><p>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).</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Building===
| + | |
| − | </div></div></div><p>First the orginal source is compiled to build the pristine package.</p><p>Then the customized source is compiled to build the server subpackage.</p><p>Any pdf files found in the original or customized source after compilation are extracted as documentation files.</p><p>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.</p><p>The server is then configured to send its log messages to the system logger rather than using local files.</p><p>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.</p><p>As a last step, the documentation for the Source-RPM (this text!) is generated.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Packaging===
| + | |
| − | </div></div></div><p>The build results are installed in a root file system as they should appear on the target system when they get installed.</p><p>In addition to the compiled code, some support files are installed for additonal Linux-specific functionality:</p><p>A file is dropped into /etc/profile.d to set the ADEMPIERE_HOME environment variable on a system-wide level.</p><p>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.</p><p>A desktop file is dropped into /usr/share/applications to include the Adempiere client in the users' desktop menu.</p><p>Documentation files are placed into the /usr/share/doc directory.</p><p>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.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Installation on the Target System===
| + | |
| − | </div></div></div><p>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).</p><div><div class="titlepage"><div><div>
| + | |
| − | ====Installation====
| + | |
| − | </div></div></div><div class="informaltable"><table border="1"><tr><th align="left">Step</th><th align="center">Client</th><th align="center">Server</th><th align="center">Pristine</th></tr><tr><td rowspan="3" align="left">pre-install</td><td align="center">---</td><td align="center">create <code class="code">adempiere</code> user</td><td align="center">---</td></tr><tr><td colspan="3" align="center">create user home directory</td></tr><tr><td colspan="3" align="center">configure rsyslog</td></tr><tr><td align="left">install</td><td colspan="3" align="center">install files</td></tr><tr><td rowspan="2" align="left">post-install</td><td colspan="2" align="center">create ADEMPIERE_HOME symbolic link</td><td align="center">---</td></tr><tr><td align="center">---</td><td align="center">autostart server on system boot</td><td align="center">---</td></tr></table></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Upgrade====
| + | |
| − | </div></div></div><div class="informaltable"><table border="1"><tr><th align="left">Step</th><th align="center">Client</th><th align="center">Server</th><th align="center">Pristine</th></tr><tr><td rowspan="3" align="left">pre-install</td><td align="center">---</td><td align="center">create <code class="code">adempiere</code> user</td><td align="center">---</td></tr><tr><td colspan="3" align="center">create user home directory</td></tr><tr><td colspan="3" align="center">configure rsyslog</td></tr><tr><td align="left">install</td><td colspan="3" align="center">install new files</td></tr><tr><td rowspan="2" align="left">post-install</td><td colspan="2" align="center">create <code class="varname">ADEMPIERE_HOME</code> symbolic link</td><td align="center">---</td></tr><tr><td align="center">---</td><td align="center">autostart server on system boot</td><td align="center">---</td></tr><tr><td align="left">pre-uninstall</td><td colspan="3" align="center">---</td></tr><tr><td align="left">uninstall</td><td colspan="3" align="center">remove old files</td></tr><tr><td align="left">post-uninstall</td><td align="center">---</td><td align="center">restart server</td><td align="center">---</td></tr></table></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ====Removal====
| + | |
| − | </div></div></div><div class="informaltable"><table border="1"><tr><th align="left">Step</th><th align="center">Client</th><th align="center">Server</th><th align="center">Pristine</th></tr><tr><td rowspan="3" align="left">pre-uninstall</td><td align="center">---</td><td align="center">stop server</td><td align="center">---</td></tr><tr><td colspan="3" align="center">unconfigure autostart of server on system boot if no other server packages are installed</td></tr><tr><td colspan="3" align="center">remove <code class="varname">ADEMPIERE_HOME</code> symbolic link if it points to this installation</td></tr><tr><td align="left">uninstall</td><td colspan="3" align="center">remove old files</td></tr><tr><td rowspan="7" align="left">post-uninstall</td><td colspan="3" align="center">remove installation directory</td></tr><tr><td colspan="3" align="center">unconfigure rsyslog if no more server installations exist</td></tr><tr><td colspan="3" align="center">unconfigure system-wide setting of <code class="varname">ADEMPIERE_HOME</code> if no more server or client installations exist</td></tr><tr><td colspan="3" align="center">remove desktop menu entry if no more server or client installations exist</td></tr><tr><td colspan="3" align="center">remove <code class="varname">ADEMPIERE_HOME</code> symbolic link if no more server or client installations exist</td></tr><tr><td colspan="3" align="center">remove user home directory and documentation if no other installations exist</td></tr><tr><td colspan="3" align="center">create <code class="varname">ADEMPIERE_HOME</code> symbolic link to newest server or client if any server or client installations exist</td></tr></table></div></div></div></div><div class="footnotes"><br><hr width="100" align="left"><div><p><sup>[<span id="ftn.id2601867" class="para">1</span>] </sup>Which means that according to the FHS,
| + | |
| − | <span class="productname">Adempiere</span> should always be installed in <code class="filename">/opt/adempiere</code>.</p></div><div><p><sup>[<span id="ftn.id2602316" class="para">2</span>] </sup>The <span class="quote">“<span class="quote">2</span>”</span> is presumabely a remnant from the days before <span class="productname">Adempiere</span>
| + | |
| − | forked from <span class="productname">Compiere</span>, where these scripts where used to control the new version 2
| + | |
| − | server, as opposed to <span class="command"><strong>RUN_Server.sh</strong></span> and <span class="command"><strong>RUN_ServerStop.sh</strong></span> controlling
| + | |
| − | the old version 1 server, which has since been lost.</p></div></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Preparing the Package Building Environment=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Required Development Tools==
| + | |
| − | </div></div></div><p>Install the tools required for building the Adempiere RPM. (This needs to be done as root).</p><div class="informalexample"><p># yum install rpm-build rpmdevtools gnupg mercurial java-1.6.0-openjdk-devel desktop-file-utils docbook5-style-xsl libxslt fop</p></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==RPM Build Tree==
| + | |
| − | </div></div></div><p>Create the RPM build tree in your home directory.</p><div class="informalexample"><p>$ rpmdev-setuptree</p></div><p>This command creates the following directory tree required by rpmbuild and configures your build settings in ~/.rpmmacros</p><pre class="programlisting">
| + | |
| − | rpmbuild
| + | |
| − | +-- BUILD
| + | |
| − | +-- RPMS
| + | |
| − | +-- SOURCES
| + | |
| − | +-- SPECS
| + | |
| − | +-- SRPMS
| + | |
| − | </pre><p>You can move the generated rpmbuild directory to any place you like, but then you must adjust the %_topdir setting in ~/.rpmmacros to point to that location.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Digital Signature==
| + | |
| − | </div></div></div><p>For security reasons, the packages you build should be digitally signed. The digital signature allows users to verify that the package has been built by you, a trusted source, and has not been tampered with since then.</p><p>First, generate a public/private key pair with the gpg --gen-key command:</p><pre class="programlisting">
| + | |
| − | <code class="prompt">$ </code><span class="command"><strong>gpg --gen-key</strong></span>
| + | |
| − | gpg (GnuPG) 1.4.10; Copyright (C) 2008 Free Software Foundation, Inc.
| + | |
| − | This is free software: you are free to change and redistribute it.
| + | |
| − | There is NO WARRANTY, to the extent permitted by law.
| + | |
| − | | + | |
| − | Please select what kind of key you want:
| + | |
| − | (1) RSA and RSA (default)
| + | |
| − | (2) DSA and Elgamal
| + | |
| − | (3) DSA (sign only)
| + | |
| − | (4) RSA (sign only)
| + | |
| − | Your selection? <strong><code>1</code></strong>
| + | |
| − | RSA keys may be between 1024 and 4096 bits long.
| + | |
| − | What keysize do you want? (2048) <strong><code>2048</code></strong>
| + | |
| − | Requested keysize is 2048 bits
| + | |
| − | Please specify how long the key should be valid.
| + | |
| − | 0 = key does not expire
| + | |
| − | <n> = key expires in n days
| + | |
| − | <n>w = key expires in n weeks
| + | |
| − | <n>m = key expires in n months
| + | |
| − | <n>y = key expires in n years
| + | |
| − | Key is valid for? (0) <strong><code>0</code></strong>
| + | |
| − | Key does not expire at all
| + | |
| − | Is this correct? (y/N) <strong><code>y</code></strong>
| + | |
| − | | + | |
| − | You need a user ID to identify your key; the software constructs the user
| + | |
| − | ID from the Real Name, Comment and Email Address in this form:
| + | |
| − | "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"
| + | |
| − | | + | |
| − | Real name: <strong><code>www.mycompany.com</code></strong>
| + | |
| − | Email address: <strong><code>devnull@mycompany.com</code></strong>
| + | |
| − | Comment: <strong><code>rpm signature</code></strong>
| + | |
| − | | + | |
| − | You selected this USER-ID:
| + | |
| − | "www.mycompany.com (rpm signature) <devnull@mycompany.com>"
| + | |
| − | | + | |
| − | Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <strong><code>O</code></strong>
| + | |
| − | You need a Passphrase to protect your secret key.
| + | |
| − | | + | |
| − | Enter passphrase: <strong><code>secret passphrase</code></strong>
| + | |
| − | Repeat passphrase: <strong><code>secret passphrase</code></strong>
| + | |
| − | | + | |
| − | We need to generate a lot of random bytes. It is a good idea to perform
| + | |
| − | some other action (type on the keyboard, move the mouse, utilize the
| + | |
| − | disks) during the prime generation; this gives the random number
| + | |
| − | generator a better chance to gain enough entropy.
| + | |
| − | .+++++
| + | |
| − | ........+++++
| + | |
| − | ..+++++
| + | |
| − | gpg: key F9D8EE90 marked as ultimately trusted
| + | |
| − | public and secret key created and signed.
| + | |
| − | | + | |
| − | gpg: checking the trustdb
| + | |
| − | gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model
| + | |
| − | gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
| + | |
| − | pub 2048R/F9D8EE90 2010-10-17
| + | |
| − | Key fingerprint = 983D 704A 024A 861F 9FCB 5CA2 4875 7B66 F9D8 EE90
| + | |
| − | uid www.mycompany.com (rpm signature) <devnull@mycompany.com>
| + | |
| − | sub 2048R/496CD9ED 2010-10-17
| + | |
| − | </pre><p>Next, the public key needs to be extracted:</p><div class="informalexample"><p>$ gpg --export --armor www.mycompany.com > MYCOMPANY-RPM-GPG-KEY</p></div><p>This file needs to be publicly distributed so that users can verify the signature of the RPM packages which you built and signed.</p><p>Finally, you need to configure rpmbuild to use the signature you just created by adding the %_signature and %_gpg_name macros to the .rpmmacros file in your home directory. The file should now look something like this:</p><pre class="programlisting">
| + | |
| − | %_topdir /home/<em>username</em>/rpmbuild
| + | |
| − | %_signature gpg
| + | |
| − | %_gpg_name www.mycompany.com (rpm signature) <devnull@mycompany.com>
| + | |
| − | …
| + | |
| − | …
| + | |
| − | </pre></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Using the Adempiere SRPM=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Installing the Source-RPM==
| + | |
| − | </div></div></div><p>Once your package building environment has been set up, you can download and unpack the Adempiere source RPM:</p><div class="informalexample"><p>$ wget -q http://adempiere.hg.sourceforge.net/hgroot/adempiere/adempiere/raw-file/tip/utils/unix/adempiere.srpm</p><p>$ rpm -ivH adempiere.srpm</p></div><p>The source files will have been installed in ~/rpmbuild/SOURCES, and the specification file ("Spec" file) in ~/rpmbuild/SPECS/adempiere.spec</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Configuring the Build Process==
| + | |
| − | </div></div></div><p>Build behavior is controlled by various parameters which are set at the beginning of the Spec File. See Appendix A for a detailed description.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Adding Customizations==
| + | |
| − | </div></div></div><p>Additional sources and patches can be added to the SOURCES directory to apply extensions and customizations to the Adempiere source code.</p><p>As new files are added, the SOURCES directory quickly gets very messy. For this reason, the files distributed with the Source-RPM are prefixed with sXXX_ (for sources) and pXXX_ (for patches), where XXX corresponds to the patch or source number in the Spec File. Users are encouraged to name their sources and patches following the same naming scheme.</p><p>Sources and patches must be listed in the Spec File using the Source<number>: filename and Patch<number>: filename pragmas.</p><p>Source and patch numbers 0-99 are reserved for the maintainer of the Adempiere source RPM, so you may add source files and patches starting with number 100.</p><pre class="programlisting">
| + | |
| − | …
| + | |
| − | …
| + | |
| − | # Sources
| + | |
| − | # -------
| + | |
| − | | + | |
| − | # standard sources
| + | |
| − | …
| + | |
| − | …
| + | |
| − | | + | |
| − | # your custom sources come here
| + | |
| − | # (start with number 100)
| + | |
| − | Source100: s100_MMyModel.java
| + | |
| − | Source101: s101_myScript.sh
| + | |
| − | | + | |
| − | | + | |
| − | # Patches
| + | |
| − | # -------
| + | |
| − | | + | |
| − | # standard patches
| + | |
| − | …
| + | |
| − | …
| + | |
| − | | + | |
| − | # your custom patches come here
| + | |
| − | # (start with number 100)
| + | |
| − | Patch100: p100_myPatch1.patch
| + | |
| − | Patch101: p101_myPatch2.patch
| + | |
| − | …
| + | |
| − | …
| + | |
| − | </pre><p>The sources and patches thus defined in the Spec File's preamble must be installed or applied in the %prep section, which is usually done with the install shell command and %patch macro.</p><pre class="programlisting">
| + | |
| − | …
| + | |
| − | …
| + | |
| − | %prep
| + | |
| − | …
| + | |
| − | …
| + | |
| − | cd $rpmBuildDir/source/custom
| + | |
| − | | + | |
| − | # standard patches
| + | |
| − | # ----------------
| + | |
| − | …
| + | |
| − | …
| + | |
| − | | + | |
| − | # install your sources here
| + | |
| − | # -------------------------
| + | |
| − | install -pD -m0644 %{SOURCE100} base/src/org/adempiere/model/MMyModel.java
| + | |
| − | install -pD -m0755 %{SOURCE101} utils/myScript.sh
| + | |
| − | | + | |
| − | # apply your patches here
| + | |
| − | # -----------------------
| + | |
| − | %patch -P100 -p1
| + | |
| − | %patch -P101 -p1
| + | |
| − | …
| + | |
| − | …
| + | |
| − | </pre><p>The install command works like cp, with the addition that it will create all leading components in the path to the target file if they are missing (-D option), preserve the source file's timestamp (-p option), and set the permission mode of the target file (-m option).</p><p>The %patch macro invokes the patch command to apply patches to the source. The patch file number is specified with the -P (upper case P) option, and the -p (lower case p) option tells the patch command how many leading slashes and directories are to be omitted from filenames in the patch file. This will be explained in the next chapter.</p><p>For building Adempiere packages, the %patch macro has been extended to accept following additional parameters:</p><div><dl>
| + | |
| − | ;-F fuzz factor
| + | |
| − | :<p>Use the given fuzz factor</p>
| + | |
| − | ;-d directory
| + | |
| − | :<p>change to directory before doing anything</p>
| + | |
| − | ;-a filename
| + | |
| − | :<p>Apply patch only if filename exists.</p><p>If filename starts with a /, it describes an absolute path, otherwise it is relative to RPM_BUILD_DIR.</p>
| + | |
| − | ;-x regular expression
| + | |
| − | :<p>requires -a.</p><p>Apply patch only if regular expression exists in filename.</p><p>If regular expression starts with a !, apply patch only if regular expression does not exist in filename.</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Building the RPM packages==
| + | |
| − | </div></div></div><p>Packages are generated using the rpmbuild --sign -b… /path/to/adempiere.spec command, where the --sign option will sign the package using the gpg-signature we created earlier, and the stage up to which the packages are built is defined with the -b… switch:</p><div><dl>
| + | |
| − | ;-bp
| + | |
| − | :<p>build up to "prep" phase only, which means downloading the source and applying patches.</p>
| + | |
| − | ;-bc
| + | |
| − | :<p>build up to "build" phase only, which means compiling the source.</p>
| + | |
| − | ;-bi
| + | |
| − | :<p>build up to "install" phase only, the resulting files are installed in a directory structure as they would be on the target machine.</p>
| + | |
| − | ;-bb
| + | |
| − | :<p>build binary packages (adempiere-….noarch.rpm, adempiere-server-….noarch.rpm, adempiere-client-….noarch.rpm).</p>
| + | |
| − | ;-bs
| + | |
| − | :<p>build source package (adempiere-….srpm).</p>
| + | |
| − | ;-ba
| + | |
| − | :<p>build all packages (both binary and source).</p></dl></div><div class="informalexample"><p>rpmbuild --sign -ba ~/rpmbuild/SPECS/adempiere.spec</p></div><p>The resulting RPM packages can be found in ~/rpmbuild/RPMS/noarch, and the source RPM in ~/rpmbuild/SRPMS.</p><p>When using --sign, rpmbuild will prompt you for a passphrase. Enter the same phrase which was used when the gpg key was generated.</p></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Creating Patches=
| + | |
| − | </div><p>Patches are text files generated by the diff tool which compares files or directories and records the differences in a certain format. Those differences can then be re-applied to the original source using patch.</p><p>To create a patch file, you therefore need the original source and a copy. You can program your changes by editing, adding, or deleting files in the copy. Then use diff to compare the original source with the changes you made in the copy and record those changes in a patch file.</p><p>Normally you would want to add your changes to source files to which all previous patches have already been applied. You can obtain the patched source code by using the -bp option with rpmbuild, which downloads the code and applies all patches.</p><div class="informalexample"><p>$ rpmbuild -bp ~/rpmbuild/SPECS/adempiere.spec</p></div><p>Then you can copy the source directory to new locations, one ending on .orig and the other ending on .new.</p><div class="informalexample"><p>$ cp -r ~/rpmbuild/BUILD/adempiere-…/source/custom adempiere.orig</p><p>$ cp -r ~/rpmbuild/BUILD/adempiere-…/source/custom adempiere.new</p></div><p>Start hacking your heart out and make any changes you want in adempiere.new. [[#ftn.id2604446|3]] When you are done, go back to the parent directory and run diff to compare adempiere.orig with adempiere.new</p><div class="informalexample"><p>$ diff -durNbB adempiere.orig adempiere.new > myPatch.patch</p></div><p>These are the options used in above diff command: ;-d :forces diff to search for smaller sets of changes than it normally would ;-u :generates unified output format, which is required by patch ;-r :recursively compare subdirectories ;-N :if a file is only found in one directory, treat it as present but empty in the other directory ;-b :ignores changes only in whitespace ;-B :ignores changes only in blank lines</p><p>The resulting patch file can be added to the SOURCES directory and listed in the Spec File as previously explained.</p><p>Note that when the patch file was created, you were in the parent directory which contains the source directory tree. But when the patch is being applied by rpmbuild, you will actually be inside the source directory tree. Therefore, the first directory component of filenames generated by diff must be ignored when running the patch command. This is achieved by passing -p1 to patch.</p><div class="footnotes"><br><hr width="100" align="left"><div><p><sup>[<span id="ftn.id2604446" class="para">3</span>] </sup>
| + | |
| − | Be careful not to actually compile the code! You only want to save changes made to the source code.
| + | |
| − | But if you compile the code, many new files will be created which do not exist in the original source, and
| + | |
| − | <span class="command"><strong>diff</strong></span> would regard all of those files as additions you made to the source.
| + | |
| − | </p></div></div>
| + | |
| − | | + | |
| − | <div>
| + | |
| − | =Distributing RPM Packages=
| + | |
| − | </div><div><div class="titlepage"><div><div>
| + | |
| − | ==Installing with RPM==
| + | |
| − | </div></div></div><p>The binary packages generated by rpmbuild can now be installed on target machines using the rpm command. Before doing so, the public GPG key must be loaded into the rpm database. Both must be done as root.</p><div class="informalexample"><p># rpm --import MYCOMPANY-RPM-GPG-KEY</p><p># rpm --ivH adempiere-server-….noarch.rpm</p><p>or</p><p># rpm --ivH adempiere-client-….noarch.rpm</p></div><p>But of course it would be much more efficient to have a central repository from which client machines can use tools like yum for automatic installation and upgrading.</p><p>Distributing the server package through a central yum repository might not be such a good idea, especially if it was built using pre-configured settings. That would enable anybody to download the server package and access critical information such us database passwords. And anyway, servers should always be upgraded manually.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Creating a YUM Repository==
| + | |
| − | </div></div></div><p>A web server is needed to distribute packages from a yum repository. The httpd server can be installed using yum, and for our purposes it can be started out of the box without having to configure it. Below commands have to be run as root.</p><div class="informalexample"><p># yum install httpd createrepo</p><p># service httpd start</p></div><p>Create an adempiere directory under /var/www/html, and copy the GPG public key and the RPM packages to be distributed into it. Make sure that everybody has read permissions for those files.</p><div class="informalexample"><p>$ mkdir -p /var/www/html/adempiere</p><p>$ cp MYCOMPANY-RPM-GPG-KEY /var/www/html/adempiere/</p><p>$ cp adempiere-….noarch.rpm /var/www/html/adempiere/</p><p>$ chmod o+x /var/www/html/adempiere</p><p>$ chmod -R o+r /var/www/html/adempiere</p></div><p>Create the repository by executing createrepo . (the last dot is important!) inside /var/www/html/adempiere</p><div class="informalexample"><p>$ cd /var/www/html/adempiere</p><p>$ createrepo .</p></div><p>Your yum repository is now up and running and can be accessed from client machines.</p><p>For distributing upgrades, simply drop the new RPM files into the repository and run createrepo . again.</p></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Installing with YUM==
| + | |
| − | </div></div></div><p>Before being able to use your new Adempiere repository, client machines must be aware that it exists. As root, create a file adempiere.repo in /etc/yum.repos.d with following contents:</p><pre class="programlisting">
| + | |
| − | [adempiere]
| + | |
| − | name=Adempiere
| + | |
| − | baseurl=http://<em>address.of.your.web.server</em>/adempiere
| + | |
| − | enabled=1
| + | |
| − | </pre><p>And of course the public key for signature verification must be imported into the RPM database (needs to be done as root):</p><div class="informalexample"><p># rpm --import http://address.of.your.web.server/adempiere/MYCOMPANY-RPM-GPG-KEY</p></div><p>Now yum can be used to install, upgrade, or remove your Adempiere packages:</p><div class="informalexample"><p># yum install adempiere-client</p><p>or</p><p># yum upgrade adempiere-client</p><p>or</p><p># yum remove adempiere-client</p></div><p>If the client machine has daily run of yum enabled, it will automatically upgrade to the newest package published in the adempiere repository.</p>
| + | |
| − | | + | |
| − | </div>
| + | |
| − | =Configuration Parameters=
| + | |
| − | <div><div class="titlepage"><div><div></div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==General Settings==
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;name
| + | |
| − | :<p>The name of the resulting package</p><p>default: adempiere</p><p>example: %global name adempiere</p>
| + | |
| − | ;company
| + | |
| − | :<p>The name of the packager (your company)</p><p>default: custom</p><p>example: %global company Some Company, Inc.</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Compile Settings==
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;applyQuickFix
| + | |
| − | :<p>whether quick fixes should be applied</p><p>Sometimes the source does not compile and some quick fixes or workarounds must be applied. The script SOURCES/s041_quickFix.sh is called to apply such workarounds.</p><p>values: 0 = do not apply quick Fixes1 = apply quick Fixes</p><p>default: 1</p><p>example: %global applyQuickFix 1</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Version Settings==
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;version
| + | |
| − | :<p>the Adempiere version to download and compile</p><p>values: current, head = download newest files of the current Adempiere versionrelease = download original files of the current Adempiere version as it was originally releasedprevious = download newest files of the previous Adempiere version (just before it changed to the current version)version = specific Adempiere version to download</p><p>Note that versions are relative to the current branch (see hgBranch) in the Mercurial repository.</p><p>When comparing the Adempiere version with tags in the Mercurial repository, both are converted to lower-case, all non-alphanumeric characters are stripped, and any "adempiere" or "release" prepending the version number are removed. Thus release-2.5.3b-initial becomes 253binitial, adempiere340-trunk-frozen becomes 340trunkfrozen, and Adempiere360LTS becomes 360lts.</p><p>default: current</p><p>example: %global version 360lts</p><p>Alternatively, it is possible to directly specify a Mercurial revision. In this case it is assumed that you know what you are doing, and no further sanity checks are performed. This also overrides any settings in the hgBranch parameter.</p><p>tip = download the current Mercurial tiphgrevision = download specific Mercurial revision</p><p>Prefixing the version information with hg will prevent such transformation and it will be treated as literal string.</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Mercurial Settings==
| + | |
| − | </div></div></div><p>Mercurial is needed to download the source code as well as gather information on the version.</p><div><dl>
| + | |
| − | ;hgOptions
| + | |
| − | :<p>general options to use with the hg command</p><p>default: --noninteractive --encoding utf8</p><p>example: %global hgOptions --quiet --noninteractive --encoding utf8</p>
| + | |
| − | ;hgRepository
| + | |
| − | :<p>URL of the source code repository</p><p>default: http://adempiere.hg.sourceforge.net:8000/hgroot/adempiere/adempiere</p><p>example: %global hgRepository http://adempiere.hg.sourceforge.net/hgroot/adempiere/adempiere</p>
| + | |
| − | ;hgBranch
| + | |
| − | :<p>Named branch in the source code repository</p><p>values: master = the main stable branch containing official releasesdevelopment = the main development branch with newest features and bugfixesrelease/name = temporary branch with "frozen" code of the next release candidatehotfix/name = temporary branch for fixing bugs found in live production version of master branchname = any other named branch</p><p>default: master</p><p>example: %global hgBranch master</p>
| + | |
| − | ;hgVersionFile
| + | |
| − | :<p>the file from which to read version information</p><p>default: base/src/org/compiere/Adempiere.java</p><p>example: %global hgVersionFile base/src/org/compiere/Adempiere.java</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Adempiere User Settings==
| + | |
| − | </div></div></div><p>OS level environment settings for the 'adempiere' user</p><div><dl>
| + | |
| − | ;userDir
| + | |
| − | :<p>the home directory of the adempiere user</p><p>(this will be the parent directory of ADEMPIERE_HOME)</p><p>default: /opt/adempiere</p><p>example: %global userDir /opt/adempiere</p>
| + | |
| − | ;adempiereHome
| + | |
| − | :<p>the location of ADEMPIERE_HOME</p><p>If starting with a /, it is the absolute path to ADEMPIERE_HOME. Otherwise it will be a subdirectory under %{userDir}.</p><p>Note that %{adempiereHome} will not actually be a directory, but a symbolic link.</p><p>The package will be installed under %{userDir} with version information, for example /opt/adempiere/adempiere360lts for the pristine package/opt/adempiere/server360lts for the server package/opt/adempiere/client360lts for the client package</p><p>Then a symbolic link will be created from the package directory to %{adempiereHome}, for example ln -s /opt/adempiere/server360lts /opt/adempiere/adempiere</p><p>This way it is possible to have different packages and versions installed on the same machine, and by changing the symbolic link you can choose which version to run.</p><p>default: adempiere</p><p>example: %global adempiereHome /opt/adempiere/adempiere</p>
| + | |
| − | ;userName
| + | |
| − | :<p>the name of the adempiere user</p><p>default: adempiere</p><p>example: %global userName adempiere</p>
| + | |
| − | ;userID
| + | |
| − | :<p>the user ID number for the adempiere user</p><p>If the requested user ID is already taken, the next available system ID will be used.</p><p>values: 200 <= x < 500</p><p>default: 215</p><p>example: %global userID 215</p>
| + | |
| − | ;groupName
| + | |
| − | :<p>the adempiere user's private group name</p><p>default: same as %{userName}</p><p>example: %global groupName adempiere</p>
| + | |
| − | ;groupID
| + | |
| − | :<p>the primary group ID number for the adempiere user</p><p>If the requested group ID is already taken, the next available system ID will be used.</p><p>values: 200 <= x < 500</p><p>default: 215</p><p>example: %global groupID 215</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Pristine Package Settings==
| + | |
| − | </div></div></div><p>The pristine package is the release as distributed by Adempiere without any extensions or patches. It can be used for testing before filing support requests or bug reports.</p><p>It contains both server and client, and it is not pre-configured.</p><div><dl>
| + | |
| − | ;buildPristine
| + | |
| − | :<p>whether to build the pristine package</p><p>values: 0 = do not build the pristine package1 = build the pristine package</p><p>default: 0</p><p>example: %global buildPristine 0</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Client Package Settings==
| + | |
| − | </div></div></div><p>The client package is installed on remote machines.</p><p>It includes desktop menu entries for connection to the server.</p><p>The client package is a custom release to which patches and extensions are applied.</p><div><dl>
| + | |
| − | ;buildClient
| + | |
| − | :<p>whether to build the client package</p><p>values: 0 = do not build the client package1 = build the client package</p><p>default: 1</p><p>example: %global buildClient 1</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Server Package Settings==
| + | |
| − | </div></div></div><p>The server package is the live server. It also includes its own client.</p><p>The server package is a custom release to which patches and extensions are applied.</p><div><dl>
| + | |
| − | ;buildServer
| + | |
| − | :<p>whether to build the server package</p><p>values: 0 = do not build the server package1 = build the server package</p><p>default: 1</p><p>example: %global buildServer 1</p>
| + | |
| − | ;preconfigureServer
| + | |
| − | :<p>whether to pre-configure the server so that it will run out of the box without executing ./RUN_Setup.sh</p><p>values: 0 = do not pre-configure the server package1 = pre-configure the server package</p><p>default: 0</p><p>example: %global preconfigureServer 0</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Server Configuration Parameters==
| + | |
| − | </div></div></div><p>These parameters are used for pre-configuring the server</p><div><div class="titlepage"><div><div>
| + | |
| − | ===Certificate Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;serverFQDN
| + | |
| − | :<p>The fully qualified domain name of the server</p><p>This string is used to identify the application server as well generate default entries for mail and database server.</p><p>default: localhost.localdomain</p><p>example: %global serverFQDN myAppServer.mydomain.com</p>
| + | |
| − | ;keystore
| + | |
| − | :<p>the server's keystore file (relative to ADEMPIERE_HOME)</p><p>default: keystore/myKeystore</p><p>example: %global keystore keystore/myKeystore</p>
| + | |
| − | ;keystorePass
| + | |
| − | :<p>the password for the server's keystore</p><p>default: adempiere</p><p>example: %global keystorePass adempiere</p>
| + | |
| − | ;keystoreCN
| + | |
| − | :<p>The CN (common name) component of the DN (distinguished name) for the server's keystore.</p><p>default: name portion of serverFQDN</p><p>example: %global keystoreCN myAppServer</p>
| + | |
| − | ;keystoreOU
| + | |
| − | :<p>The OU (organizational unit) component of the DN (distinguished name) for the server's keystore.</p><p>default: name of currently logged-in user</p><p>example: %global keystoreOU myName</p>
| + | |
| − | ;keystoreO
| + | |
| − | :<p>The O (organization) component of the DN (distinguished name) for the server's keystore.</p><p>default: AdempiereUser</p><p>example: %global keystoreO AdempiereUser</p>
| + | |
| − | ;keystoreL
| + | |
| − | :<p>The L (location) component of the DN (distinguished name) for the server's keystore.</p><p>default: myTown</p><p>example: %global keystoreL myTown</p>
| + | |
| − | ;keystoreST
| + | |
| − | :<p>The ST (state) component of the DN (distinguished name) for the server's keystore.</p><p>default: myState</p><p>example: %global keystoreST myState</p>
| + | |
| − | ;keystoreC
| + | |
| − | :<p>The C (country) component of the DN (distinguished name) for the server's keystore.</p><p>default: country from system's LANG setting in /etc/sysconfig/i18n</p><p>example: %global keystoreC US</p>
| + | |
| − | ;keystoreCodeAlias
| + | |
| − | :<p>the certificate alias for code signing on the server</p><p>Note that although this is a configurable parameter, the alias 'adempiere' is hardcoded in some source files, so it might be a bad idea to change it.</p><p>default: adempiere</p><p>example: %global keystoreCodeAlias adempiere</p>
| + | |
| − | ;keystoreWebAlias
| + | |
| − | :<p>the certificate alias for secure web connections to the server</p><p>Note that although this is a configurable parameter, the alias 'adempiere' is hardcoded in some source files, so it might be a bad idea to change it.</p><p>default: adempiere</p><p>example: %global keystoreWebAlias adempiere</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Java Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;javaType
| + | |
| − | :<p>the Java type installed on the server</p><p>Note that ibm is not implemented yet, and there are still some issues with openJDK.</p><p>values: sun, mac, ibm, OpenJDK</p><p>default: OpenJDK</p><p>example: %global javaType OpenJDK</p>
| + | |
| − | ;javaHome
| + | |
| − | :<p>the Java path on the server</p><p>default: /usr/lib/jvm/java-openjdk</p><p>example: %global javaHome /usr/lib/jvm/java-openjdk</p>
| + | |
| − | ;javaOptions
| + | |
| − | :<p>options with which to start the virtual machine under which Adempiere is run</p><p>(see Java documentation)</p><p>default: -Xms64M -Xmx512M</p><p>example: %global javaOptions -Xms64M -Xmx512M</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Application Server Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;serverType
| + | |
| − | :<p>the type of application server</p><p>values: jboss, glassfish</p><p>default: jboss</p><p>example: %global serverType jboss</p>
| + | |
| − | ;deployDir
| + | |
| − | :<p>the application server deployment directory (relative to ADEMPIERE_HOME)</p><p>default: jboss/server/adempiere/deploy for JBossglassfish/glassfish/domains/domain1 for Glassfish</p><p>example: %global deployDir jboss/server/adempiere/deploy</p>
| + | |
| − | ;jnpPort
| + | |
| − | :<p>the JNP port (whatever that is)</p><p>default: 1099 for JBoss3700 for Glassfish</p><p>example: %global jnpPort 1099</p>
| + | |
| − | ;webPort
| + | |
| − | :<p>the TCP port to be used by the application server for HTTP</p><p>default: 8888</p><p>example: %global webPort 8888</p>
| + | |
| − | ;sslPort
| + | |
| − | :<p>the TCP port to be used by the application server for HTTPS</p><p>default: 8443</p><p>example: %global sslPort 8443</p>
| + | |
| − | ;logFacility
| + | |
| − | :<p>which facility to use for the system logger</p><p>values: local0 … local7</p><p>default: local1</p><p>example: %global logFacility local1</p>
| + | |
| − | ;logLevel
| + | |
| − | :<p>the minimum severity level for messages to be logged</p><p>values: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY</p><p>default: INFO</p><p>example: %global logLevel INFO</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===Database Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;dbServer
| + | |
| − | :<p>the name of the database server</p><p>default: name portion of %{serverFQDN} (assuming that Adempiere is installed on the same machine as the database)</p><p>example: %global dbServer myDatabaseServer</p>
| + | |
| − | ;dbType
| + | |
| − | :<p>the type of database (database vendor)</p><p>values: oracle, oracleXE, postgresql</p><p>default: postgresql</p><p>example: %global dbType postgresql</p>
| + | |
| − | ;dbPort
| + | |
| − | :<p>the database port</p><p>default: 5432 for PostgreSQL1521 for Oracle</p><p>example: %global dbPort 1521</p>
| + | |
| − | ;dbName
| + | |
| − | :<p>the name of the database</p><p>default: adempiere for PostgreSQLorcl for Oraclexe for OracleXE</p><p>example: %global dbName adempiere</p>
| + | |
| − | ;dbUrl
| + | |
| − | :<p>the url for the jdbc driver to connect to the database</p><p>default: jdbc:postgresql://%{dbServer}:%{dbPort}/%{dbName} for PostgreSQLjdbc:oracle:thin:@//%{dbServer}:%{dbPort}/%{dbName} for Oracle</p><p>example: %global dbUrl jdbc:postgresql://myDatabaseServer:5432/adempiere</p>
| + | |
| − | ;dbUser
| + | |
| − | :<p>the name of the adempiere database user</p><p>default: adempiere</p><p>example: %global dbUser adempiere</p>
| + | |
| − | ;dbPassword
| + | |
| − | :<p>the password of the adempiere database user</p><p>default: adempiere</p><p>example: %global dbPassword adempiere</p>
| + | |
| − | ;dbSystemUser
| + | |
| − | :<p>the user name of the database system administrator</p><p>default: postgres for PostgreSQLsystem for Oracle</p><p>example: %global dbSystemUser postgres</p>
| + | |
| − | ;dbSystemPassword
| + | |
| − | :<p>the password of the database system administrator</p><p>default: postgres for PostgreSQLmanager for Oracle</p><p>example: %global dbSystemPassword postgres</p>
| + | |
| − | ;oracleHome
| + | |
| − | :<p>When using Oracle, the adempiere user needs to have access to the Oracle client on the local machine.</p><p>This is the ORACLE_HOME environment variable pointing to the oracle product directory.</p><p>To keep the adempiere packages independent of the installed Oracle version, if the Oracle product directory contains a version in its name, it is recommended to create symbolic link from the Oracle product directory to a version-free name such as /opt/oracle/oracle at the time of Oracle installation.</p><p>This can be done with the command</p><div class="informalexample"><p># ln -s /opt/oracle/product/10.2.01 /opt/oracle/oracle</p></div><p>default: /opt/oracle/oracle</p><p>example: %global oracleHome /opt/oracle/product/10.2.01</p>
| + | |
| − | ;oracleTnsAdmin
| + | |
| − | :<p>When using Oracle, the adempiere user needs to have access to the Oracle client on the local machine.</p><p>This is the TNS_ADMIN environment variable pointing to the location where Oracle Net Services look for configuration files.</p><p>default: %{oracleHome}/network/admin</p><p>example: %global oracleTnsAdmin /opt/oracle/product/10.2.01/network/admin</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===FTP Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;ftpServer
| + | |
| − | :<p>name of the FTP server</p><p>default: name portion of %{serverFQDN}</p><p>example: %global ftpServer myAppServer</p>
| + | |
| − | ;ftpPrefix
| + | |
| − | :<p>the FTP prefix to use</p><p>(no idea what this does)</p><p>default: my</p><p>example: %global ftpPrefix my</p>
| + | |
| − | ;ftpUser
| + | |
| − | :<p>the FTP user</p><p>default: anonymous</p><p>example: %global ftpUser anonymous</p>
| + | |
| − | ;ftpPassword
| + | |
| − | :<p>the FTP user's password</p><p>default: user@host.com</p><p>example: %global ftpPassword user@host.com</p></dl></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ===E-Mail Configuration===
| + | |
| − | </div></div></div><div><dl>
| + | |
| − | ;mailServer
| + | |
| − | :<p>the mail server to use</p><p>default: mailserver.(domain portion of %{serverFQDN})</p><p>example: %global mailServer mailserver.mydomain.com</p>
| + | |
| − | ;mailAddress
| + | |
| − | :<p>the default administrative mail address to use</p><p>It can be overwritten on client level</p><p>default: adempiere@(domain portion of %{serverFQDN})</p><p>example: %global mailAddress adempiere@mydomain.com</p>
| + | |
| − | ;mailUser
| + | |
| − | :<p>the user of the default mail account</p><p>default: adempiere</p><p>example: %global mailUser adempiere</p>
| + | |
| − | ;mailPassword
| + | |
| − | :<p>the password of the default mail account</p><p>default: adempiere</p><p>example: %global mailPassword adempiere</p></dl></div></div></div><div><div class="titlepage"><div><div>
| + | |
| − | ==Corporate Format Settings==
| + | |
| − | </div></div></div><p>Some sites may want to enforce their own corporate formats, i.e. no matter what locale the user is working in or what language a business partner has defined, always the same decimal point, date format, and paper size are used, regardless of what the locale conventions are.</p><p>(And the locale conventions are often wrong in Java, anyway).</p><p>This is technically a patch, but as the target file may change frequently, it would be very cumbersome to always keep the patch file up to date.</p><p>It has therefore been incorporated as a script in the %prep section.</p><div><dl>
| + | |
| − | ;useCorporateFormat
| + | |
| − | :<p>whether to apply the corporate format patch</p><p>Note that this changes the locale conventions for the complete installation and thus affects all clients.</p><p>values: 0 = do not use corporate formats1 = use corporate formats</p><p>default: 0</p><p>example: %global useCorporateFormat 0</p>
| + | |
| − | ;formatDecimal
| + | |
| − | :<p>whether to use a point as decimal separator</p><p>values: 0 = use a comma as decimal separator1 = use a point as decimal separator</p><p>default: 1</p><p>example: %global formatDecimal 1</p>
| + | |
| − | ;formatDate
| + | |
| − | :<p>the date format to use</p><p>The formats are probably described somewhere in Java documentation. Have a look at looks/src/org/compiere/util/Language.java for examples.</p><p>default: yyyy-MM-dd</p><p>example: %global formatDate yyyy-MM-dd</p>
| + | |
| − | ;formatPaper
| + | |
| − | :<p>the paper size to use.</p><p>The formats are probably described somewhere in Java documentation. Have a look at looks/src/org/compiere/util/Language.java for examples.</p><p>values: ISO.A4, NA.LETTER</p><p>default: ISO.A4</p><p>example: %global formatPaper ISO.A4</p></dl></div></div></div>
| + | |
| | [[Category:Developer documentation]] | | [[Category:Developer documentation]] |
| | [[Category:Projects and Tools]] | | [[Category:Projects and Tools]] |
