| > Licensed to the Apache Software Foundation (ASF) under one |
| > or more contributor license agreements. See the NOTICE file |
| > distributed with this work for additional information |
| > regarding copyright ownership. The ASF licenses this file |
| > to you under the Apache License, Version 2.0 (the |
| > "License"); you may not use this file except in compliance |
| > with the License. You may obtain a copy of the License at |
| > |
| > http://www.apache.org/licenses/LICENSE-2.0 |
| > |
| > Unless required by applicable law or agreed to in writing, |
| > software distributed under the License is distributed on an |
| > "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| > KIND, either express or implied. See the License for the |
| > specific language governing permissions and limitations |
| > under the License. |
| |
| # Installers |
| |
| We provide installers for various OSes (**Linux**, **Windows**, **macOSX**) and architectures (32 bits and 64 bits). We also provide |
| generic binaries which don't install a daemon. |
| |
| This document explains how those installers are working, for people who want to get deep into the process. As it, this |
| document is not targeting users, but rather developers. |
| |
| ## Supported OSes |
| |
| We support: |
| * Linux (*rpm* and *deb* packages), for 32 bits and 64 bits |
| * Mac OSX (tm), for 32 bits and 64 bits |
| * Windows, 32 bit sonly |
| * a default binary that can be installed but does not provide a daemon |
| |
| |
| ## Wrapper/daemon |
| |
| It's convenient to have a package that can be installed as a daemon. We provide such package. We use |
| a wrapper (Tanuki) |
| |
| ## Building installers |
| |
| It's quite easy. You need to be in the _installers_ module and launch _mvn clean install -P<target>_ where _<target>_ |
| is one of : |
| * **debian** : Debian installer, 32 and 64 bits |
| * **rpm** : Linux RH/CentOS installer |
| * **windows** : Windows 32 bits installer (we don't provide a 64 bits installer yet) |
| * **mac** : Mac OSX installer, 32 and 64 bits |
| * **bin** : Standard installer, 32 and 64 bits |
| * **archive** : archive - ie not an installer -. |
| * **docker** : A Docker installer |
| * **installers** : all the installers. |
| |
| NOTE: In order to be able to build the *rpm*, *windows* and *deb* packages, you need to install the following tools: |
| |
| ### On Mac OSX: |
| |
| * **deb**: *brew install dpkg*. **BEWARE**: it will install in */usr/local/bin*, instead of */usr/bin*. |
| |
| You'll need to run the installers using this command line: |
| |
| mvn clean install -Pdebian -Dinstallers.dpkg=/usr/local/bin/dpkg |
| |
| * **rpm**: *brew install rpm*. **BEWARE**: it will install in */usr/local/bin*, instead of */usr/bin*. |
| |
| You'll need to run the installers using this command line: |
| |
| mvn clean install -Prpm -Dinstallers.dpkg=/usr/local/bin/rpmbuild |
| |
| |
| * **windows**: *brew install makensis*. **BEWARE**: it will install in */usr/local/bin*, instead of */usr/bin*. |
| |
| You'll need to run the installers using this command line: |
| |
| mvn clean install -Pwindows -Dinstallers.makensis=/usr/local/bin/makensis |
| |
| ### 'bin' installer |
| |
| Building a **bin** installer generates two files : |
| * _apacheds-2.0.0.AM27-SNAPSHOT-32bit.bin_ |
| * _apacheds-2.0.0.AM27-SNAPSHOT-64bit.bin_ |
| |
| Those files are scripts concatenated with a *tar* file. The script will ask you to validate the |
| _Apache_ license, extract the tar file, launch the _install.sh_ script and cleanup temporary files once the |
| installation is done. Here is the layout of the installer once executed, before the installation is ran: |
| |
| / |
| | |
| +--/instance |
| | | |
| | +-- config.ldif |
| | | |
| | +-- etc-initd-script |
| | | |
| | +-- log4j.properties |
| | | |
| | +-- wrapper-instance.conf |
| | |
| +--/server |
| | | |
| | +--/bin |
| | | | |
| | | +-- apacheds* |
| | | | |
| | | +-- wrapper* |
| | | |
| | +--/conf |
| | | | |
| | | +-- wrapper.conf |
| | | |
| | +--/lib |
| | | | |
| | | +-- apacheds-service-2.0.0.AM27-SNAPSHOT.jar |
| | | | |
| | | +-- apacheds-wrapper-2.0.0.AM27-SNAPSHOT.jar |
| | | | |
| | | +-- libwrapper.so |
| | | | |
| | | +-- wrapper-3.2.3.jar |
| | | |
| | +-- NOTICE |
| | | |
| | +-- LICENSE |
| | |
| +--/sh |
| | |
| +-- functions.sh* |
| | |
| +-- install.sh* |
| | |
| +-- variables.sh* |
| |
| The way the _instal.sh_ script works is that it uses the _variable.sh_ file content to configure the server: |
| each variable (**@<name>@**) in the _/server/bin/apacheds_ script will be substituted with the default value or |
| the provided value. Here is an exalple of what happens when the script is executed: |
| |
| $ ./install.sh |
| Where do you want to install ApacheDS? [Default: /opt/apacheds-] |
| |
| Where do you want to install ApacheDS instances? [Default: /var/lib/apacheds-] |
| |
| What name do you want for the default instance? [Default: default] |
| |
| Where do you want to install the startup script? [Default: /etc/init.d] |
| |
| Here are the variables that can be configured : |
| |
| * **APACHEDS_HOME_DIRECTORY** /opt/apacheds-2.0.0.AM26 |
| * **INSTANCES_HOME_DIRECTORY** /var/lib/apacheds-2.0.0.AM26 |
| * **STARTUP_SCRIPT_DIRECTORY** /etc/init.d |
| * **DEFAULT_INSTANCE_NAME** default |
| * **RUN_AS_USER** apacheds |
| * **RUN_AS_GROUP** apacheds |
| |
| Once the installer has been run, the server files are located in various places : |
| |
| /opt/apacheds-2.0.0.AM27-SNAPSHOT |
| | |
| +-- /bin |
| | | |
| | +-- apacheds* |
| | | |
| | +-- wrapper* |
| | |
| +-- /conf |
| | | |
| | +-- wrapper.conf |
| | |
| +-- /lib |
| | |
| +-- apacheds-service-2.0.0.AM27-SNAPSHOT.jar |
| | |
| +-- apacheds-wrapper-2.0.0.AM27-SNAPSHOT.jar |
| | |
| +-- libwrapper.so |
| | |
| +-- wrapper-3.2.3.jar |
| . |
| . |
| . |
| /var/lib/apacheds-2.0.0.AM27-SNAPSHOT |
| | |
| +-- /default |
| | |
| +-- /conf |
| | | |
| | +-- config.ldif |
| | | |
| | +-- log4j.properties |
| | | |
| | +-- wrapper-instance.conf |
| | |
| +-- /log |
| | |
| +-- /partitions |
| | |
| +-- /run |
| . |
| . |
| . |
| /etc/rc.d/init.d |
| | |
| +-- apacheds-2.0.0.AM27-SNAPSHOT-default |
| |
| In the process, a user and group will be created if they didn't exist beforhand. |
| |
| **NOTE**: if one want to run the server with a port under **389**, there are some configuration to change, as this is a privileged port. |
| |
| |
| ### The 'bin' installer plugin |
| |
| This plugin just create the initial installer, copying various files in the right place before creating the tar file. |
| |
| At the end, it calls the _createInstaller.sh_ script that will generate the final package. |
| |
| ## Debugging a Maven plugin under Eclipse |
| |
| Debugging one of the installers maven plugins in Eclipse is quite easy: |
| |
| * First set a breakpoint in the _execute()_ function of the plugin you are interested in debugging |
| * Create a new *Maven Build* debug configuration |
| * Set the base Directory to _${workspace_loc:/apacheds-installers-2.0.0.AM27-SNAPSHOT}_ (or whatever version you are debugging). This can be done using the _workspace_ button below the input box. |
| * Set the goals to _clean install_ |
| * Set the _profile_ to match the plugin you want to debug (**mac**, **bin**, **debian**, **rpm**, **windows**, **archive**, **docker**, or **installers**) |
| * You are good to go ! |
| |
| NOTE: If you were to modify the plugin, do not forget to recompile it before debugging it ! |
