Introduction
This page documents the Apache DS installers. It explains what kind of installers are available, their internal structures and how to generate them.
Installers Architectures
As of march 2008, we have the following set of installers for Apache DS:
- A Windows executable installer (.exe)
- A Linux RPM installer (.rpm)
- A Linux DEB installer (.deb)
- A Linux BIN installer (.bin)
- A Mac OS X PKG installer (.pkg)
Default Apache DS server files layout
Every installer uses almost the same Apache DS server layout.
This layout consists in an organized set of files and directories which looks like this:
The bin directory contains the Apache DS binaries:
- apacheds (or apacheds.exe on Windows) is the specific Tanuki wrapper for the target OS & Architecture
- apacheds-tools.jar is a java utility jar contains the Apache DS tools that can be used to send various requests to the server.
The conf directory contains the Apache DS configuration files:
- apacheds.conf is the wrapper configuration (defines the JVM and classpath to use, memory usage, etc.)
- _log4j.properties is the default logging properties
- server.xml is the server configuration file (defines the protocols, partitions, interceptors, etc.)
The lib directory contains the various libraries used by Apache DS (including the Tanuki wrapper libraries)
The var directory contains three sub-directories (********************.ASK FOR INFORMATION ON WHAT THESE DIRECTORIES ARE FOR.********************)
- log
- partitions
- run
Windows executable installer
The Windows executable installer is built using NSIS (http://nsis.sourceforge.net/), an open source system to create Windows installers.
The installer can, of course, be generated a Windows system but also on a Linux or Mac OS X system (for these two systems, a preliminary step is to compile the makensis command line utility that will be used to generate the installer).
Installer Generation layout
To generate the installer, a directory is created and contains the server files. This is the default Apache DS server files layout, shared by almost every installer.
Here's the layout this directory:
Additional files such as the instances specific files (apacheds.conf, log4j.properties, server.xml) or the example ldif file (for loading example data into the default instance) are bundled into the installer and copied to their final location during the installation process.
Installation layout
Once the installer is generated, here's what it looks:
********************.ADD (A) SCREENSHOT(S) OF THE INSTALLER.********************
The installer installs the following files on the target system:
- Server files are installed at C:\\Program Files\Apache Directory Server
- Instances files are installed at C:\\Program Files\Apache Directory Server\instances
Linux RPM installer
Installer Generation layout
********************.ADD SOME TEXT.********************
Installation layout
********************.ADD SOME TEXT.********************
Linux Deb installer
Installer Generation layout
To generate the installer, a directory is created and contains a specific structure to be used with the dpkg command line utility.
Here's the layout this directory:
The DEBIAN directory contains the files needed by the dpkg command line utility to generate the Debian package:
- control holds the package information, such as the name and version of the package, target architecture, etc.
- postinst is a shell script that will be run at the end of the installation. We use it to set the proper permissions for executable files.
The three other directories at the root of the layout correspond to installed files and their location on the target system, the root of the layout acting as the root of the filesystem (/).
This way, for example, the file apacheds-1.5.2-SNAPSHOT-default inside the etc > init.d directories will be installed at /etc/init.d/apacheds-1.5.2-SNAPSHOT-default.
Installation layout
The installer installs the following files on the target system:
- Server files are installed at /opt/apacheds-1.5.2-SNAPSHOT
- Instances files are installed at /var/lib/apacheds-1.5.2-SNAPSHOT
- An init script is installed at /etc/init.d/apacheds-1.5.2-SNAPSHOT-default
Linux Binary installer
Installer Structure
The binary installer consists in an auto-extractable archive installer. It has to be run using the command line and looks like this:
It is composed of two major parts:
- a bootstrapper
- a TAR GZIP archive
The bootstrap is in charge of extracting the archive and lauching the installation.
The archive itself is composed of two parts:
- several install shell scripts
- the Apache DS files to install
This schema quickly summarize the structure of the installer:
Installer Generation layout
To generate the installer, a directory is created and contains a specific required structure.
Here's the layout this directory:
The root directory contains the server and instances files. Theses files will be installed to the locations specified by the user during the installation.
The sh directory contains the necessary shell scripts for the installation.
At the root of the layout, we find 2 others shell scripts that will be used to create the installer, createInstaller.sh and bootstrap.sh.
Installation layout
The installer installs the following files on the target system:
- Server files are installed by default at /opt/apacheds-1.5.2-SNAPSHOT or wherever the user has decided to set them
- Instances files are installed by default at /var/lib/apacheds-1.5.2-SNAPSHOT or wherever the user has decided to set them
- An init script is installed at /etc/init.d/apacheds-1.5.2-SNAPSHOT-$INSTANCE where $INSTANCE is the name of the default Apache DS instance ("default" by default)
Mac OS X installer
Installer Generation layout
To generate the installer, a directory is created and contains a specific structure to be used with the PackageMaker command line utility.
Here's the layout of this directory:
The Info.plist file contains the general information about the package (package name, version, etc.).
The Resources directory contains the resources of the Installer (License and background files).
The root directory contains the files to be installed and their location on the target system, the root directory acting as the root of the filesystem (/).
This way, for example, the file org.apache.directory.server.plist inside the root > Library > LaunchDaemons directories will be installed at /Library/LaunchDaemons/org.apache.directory.server.plist.
The generation will create a Mac OS X Installer Package called Apache Directory Server Installer.pkg.
This package is handled as a single file in the Finder but it is actually a folder (with a .pkg extension) containing a particular structure.
So, it is impossible to distribute the package file through the Internet.
To avoid this distribution problem, the package is distributed inside a DMG (Disk iMaGe).
To generate the disk image, a directory is created and contains a specific structure to be used with the hdiutil command line utility.
Here's the layout of this directory:
The dmg directory that will be used as root for the dmg contains the following files:
- a (hidden) .background directory in which is hidden the background image (baskgound.png) for the disk image.
- a (hidden) .DS_Store file holding the View Options for the disk image.
- the Apache Directory Server Installer.pkg package.
Once it is generated and mounted, the disk image will only display the Apache Directory Server Installer.pkg package, as show below:
Installation layout
The installer installs the following files on the target system:
- Server files are installed by default at /usr/local/apacheds-1.5.2-SNAPSHOT
- Instances files are installed by default at /usr/local/apacheds-1.5.2-SNAPSHOT/instances
- An init script is installed at /Library/LaunchDaemons/org.apache.directory.server.plist
Installers Projects Architecture
Installers are divided into 3 projects:
- Daemon Plugin project (/daemons/plugin/)
- Installers ApacheDS project (/installers/apacheds)
- Installers ApacheDS NoArch project (/installers/apacheds-noarch)
Daemon Plugin project
This is the main project where daemon and installers are built.
This project is a Maven 2 plugin. It defines one goal "generate", which creates installers.
This goal is defined in the ServiceInstallersMojo class and uses various installer targets:
- IzPacKTargets (Old multi-platforms installer made with IzPack)
- RpmTagets (Current RPM package installer)
- PkgTargets (Current Mac OS X PKG package installer)
- InnoTargets (Old Windows installer made with Inno)
- NsisTargets (Current Windows Installer made with NSIS)
- DebTargets (Current Deb package installer)
- BinTargets (Current Bin package installer)
Installers ApacheDS project
This projects builds the installers using the Deamon Plugin.
It only includes a "Dummy" java class and a few resources for the installers.
The setup is done in the pom.xml file of the project.
Various profiles are defined to generate different installers.
Here's an example of profile:
<profiles> <profile> <id>macosx</id> <build> <plugins> <plugin> <groupId>org.apache.directory.daemon</groupId> <artifactId>daemon-plugin</artifactId> <version>1.1.2-SNAPSHOT</version> <configuration> <application> <name>apacheds</name> <version>1.5.2-SNAPSHOT</version> <description>Apache Directory Suite</description> <icon>src/main/resources/feather.ico</icon> <copyrightYear>2007</copyrightYear> <minimumJavaVersion>1.5</minimumJavaVersion> <url>http://directory.apache.org</url> <email>users@directory.apache.org</email> <license>target/classes/META-INF/LICENSE</license> <authors> <author>Apache Directory Team</author> <author>akarasulu@apache.org</author> <author>ckoppelt@apache.org</author> <author>elecharny@apache.org</author> <author>erodriguez@apache.org</author> <author>ersiner@apache.org</author> <author>oersoy@apache.org</author> <author>pamarcelot@apache.org</author> <author>szoerner@apache.org</author> <author>seelmann@apache.org</author> <author>trustin@apache.org</author> </authors> </application> <packagedFiles> <packagedFile> <source>org.apache.directory.server:apacheds-server-tools</source> <destinationPath>bin/apacheds-tools.jar</destinationPath> <dependency>true</dependency> <installationBundleId>Binaries</installationBundleId> </packagedFile> <packagedFile> <source>target/classes/META-INF/NOTICE</source> <destinationPath>NOTICE</destinationPath> <executable>false</executable> <filtered>true</filtered> </packagedFile> </packagedFiles> <applicationClass> org.apache.ldap.server.Service </applicationClass> <pkgTargets> <pkgTarget> <id>apacheds-macosx</id> <finalName>apacheds-macosx</finalName> <osName>Mac OS X</osName> <osFamily>macosx</osFamily> <osVersion>10.5</osVersion> <osArch>x86</osArch> <daemonFramework>tanuki</daemonFramework> </pkgTarget> </pkgTargets> <excludes> <!-- apacheds-tools.jar does not get put in lib directory --> <exclude>org.apache.directory.server:apacheds-server-tools</exclude> <exclude>ant:ant</exclude> <exclude>aopalliance:aopalliance</exclude> <exclude>xerces:xerces</exclude> <!--exclude>commons-pool:commons-pool</exclude--> <exclude>xml-apis:xml-apis</exclude> <exclude>aspectwerkz:aspectwerkz-core</exclude> <exclude>velocity:velocity</exclude> <exclude>org.springframework:spring-aop</exclude> <exclude>qdox:qdox</exclude> <exclude>oro:oro</exclude> <exclude>commons-attributes:commons-attributes-compiler</exclude> <exclude>commons-attributes:commons-attributes-api</exclude> <exclude>cglib:cglib</exclude> <exclude>velocity:velocity-dep</exclude> <exclude>com.jamonapi:jamon</exclude> <exclude>asm:asm</exclude> <exclude>freemarker:freemarker</exclude> <exclude>asm:asm-util</exclude> <exclude>jasperreports:jasperreports</exclude> </excludes> </configuration> <executions> <execution> <goals> <goal>generate</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </profile>
Installers ApacheDS NoArch project
The two first projects will generate the platform specific installers that have been discussed above, while the last one will produce a tarball containing the Default Apache DS server files layout, that you can unpack where you want (it does not include the Tanuki wrapper, so this is a one-instance server only).