content/apacheds/advanced-ug/5.1-layout.mdtext

Title: 5.1 - Layout
NavPrev: 5-administration.html
NavPrevText: 5 - Administration
NavUp: 5-administration.html
NavUpText: 5 - Administration
NavNext: 5.2-start-stop.html
NavNextText: 5.2 - Starting and Stopping
Notice: 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.

# 5.1 - Layout

[TOC]

## 5.1.1 General Layout

The general layout for ApacheDS is fairly simple and consists in two major concepts:

* an installation layout
* an instance layout

### 5.1.1.1 Installation Layout

The installation is where are stored all files essential to ApacheDS like the launch script, libraries, eventually a service wrapper (depending on the kind of installer used).

The most common installation, shared by all ApacheDS installers, can be described as follows:

    :::text
    [Installation-Layout]
        |- bin/
            |- apacheds (or 'apacheds.exe' on Windows)
            |- wrapper (or 'wrapper.exe' on Windows)
        |- conf/
            |- wrapper.conf
        |- lib/
            |- apacheds-service-${version}.jar
            |- apacheds-wrapper-${version}.jar
            |- libwrapper.jnilib (or 'libwrapper.so', or 'libwrapper.dll' depending on the platform)
            |- wrapper-3.2.3.jar
        |- LICENSE
        |- NOTICE

* The _**bin/**_ directory contains the _**apacheds**_ launch script and _**wrapper**_ binary used to configure ApacheDS as a _service_.
* The _**conf/**_ directory holds the general configuration for the service in _**wrapper.conf**_.
* The _**lib/**_ directory contains all ApacheDS and wrapper libraries necessary to run the server.
* _**LICENCE**_ and _**NOTICE**_ files contains the required legal information about ApacheDS.

### 5.1.1.2 Instance Layout

ApacheDS is built to be able to run multiple instances of the server at the same time, which means that optionally an _**instances**_ folder can be found in the installation layout (or elsewhere on disk depending on the platform).
In that folder, can be found a single or multiple directories, all sharing the same layout, corresponding to all ApacheDS instance (one directory per instance, named by the id of the instance).

Here's how this instance layout can be described:

    :::text
    [Instance-Layout]
        |- cache/
            |- [...]
        |- conf/
            |- config.ldif
            |- log4j.properties
            |- wrapper.conf
        |- log/
            |- apacheds.log
            |- wrapper.log
        |- partitions/
            |- example/
                |- [...]
            |- schema/
                |- [...]
            |- system/
                |- [...]

* The _**cache/**_ directory is empty upon installation and contains all the data required for the cache system after the first start of the server.
* The _**conf/**_ directory contains:
    * an additional _**wrapper.conf**_ where general configuration defined in the installation layout can be overwritten for the given instance.
    * a _**log4j.properties**_ file which is responsible for logging configuration.
    * a _**config.ldif**_ file corresponding to the inner configuration of ApacheDS.
* The _**log/**_ directory is empty upon installation and contains two files after the first start of the server:
    * a _**apacheds.log**_ which is where all logs defined in the _**log4j.properties**_ go.
    * a _**wrapper.log**_ which only contains the wrapper logs (related to the service's start/stop).
* The _**partitions/**_ directory is empty upon installation and contains after the first start of the server a directory for each partition defined in the configuration:
    * the _**example/**_ directory holds the data for the "_example_" partition defined in ApacheDS' default configuration.
    * the _**schema/**_ and _**system/**_ directories contain the data for both internal "_schema_" and "_system_" partitions.

## 5.1.2 Specific Layouts

Depending on the type of distribution used to install ApacheDS, the layout varies to adapt as best as possible to the specificities of each platform.

### 5.1.2.1 Archive Distribution (zip/tar.gz)

The Archive distribution consist of a compressed directory containing everything needed to run ApacheDS. It doesn't install on the machine and does not require any extra permission (root user, installer password, etc.). The directory is simply unarchived and ApacheDS is ready to be launched.

The installation layout is a bit simpler for this kind of distribution since no wrapper is distributed, the application being run in a terminal or via the .bat script.

    :::text
    [Installation-Layout]
        |- bin/
            |- apacheds.bat
            |- apacheds.sh
            |- cpappend.bat
        |- instances/
        |- lib/
            |- apacheds-service-${version}.jar
        |- LICENSE
        |- NOTICE

* The _**bin/**_ directory contains the _**apacheds.bat**_ (Windows) and _**apacheds.sh**_ (Linux/Unix) launch scripts and a _**cpappend.bat**_ utility (only used on Windows).
* The _**instances/**_ directory hold all ApacheDS instances (an instance named _**default**_ is provided by default).
* The _**lib/**_ directory only contains the ApacheDS library.
* _**LICENCE**_ and _**NOTICE**_ files contains the required legal information about ApacheDS.

### 5.1.2.2 Windows Installer (.exe)

The Windows installer uses the general installation and instances layout.

By default, the installation directory is:

    C:\Program Files\ApacheDS

An _**instances/**_ directory in the installation layout holds all ApacheDS instances (an instance named _**default**_ is provided by default).

ApacheDS is registered as a service on Windows. Operations on the service can be achieved in the _**Services**_ utility which is accessible via _**Start**_ > _**Contol Panel**_ > _**Administration Tools**_ > _**Services**_.

### 5.1.2.3 Linux Binary (.bin), Debian (.deb) & Fedora (.rpm) Installers

The Mac OS X installer uses the general installation and instances layout.

By default, the installation directory is:

    /opt/apacheds-${version}

All ApacheDS instances are located in a directory at the following location (an instance named _**default**_ is provided by default):

    /var/lib/apacheds-${version}

The installer also adds a _shortcut_ launch script for the default instance at:

    /etc/init.d/apacheds-${version}-default

**NOTE:** The ApacheDS Linux Binary installer lets the user decide the locations of the installation directory, the instances directory and the default instance launch script. The locations above refer to the default location and need to be adapted to whatever path was chosen during the installation.

### 5.1.2.4 Mac OS X Installer (.pkg)

The Mac OS X installer uses the general installation and instances layout.

By default, the installation directory is:

    /usr/local/apacheds-${version}

An _**instances/**_ directory in the installation layout holds all ApacheDS instances (an instance named _**default**_ is provided by default).

The installer also adds a _shortcut_ to the command in the _**bin**_ directory called "_**apacheds**_", accessible directly in a terminal and located at:

    /usr/bin/apacheds