# Deployment Framework Structure

This page describes directory structure of the Deployment Framework.

## Directory hierarchy

The Deployment Framework has the following directory hierarchy. Files and directories packaged with the framework are shown in black; files and directories added as a result of deploying components are shown in grey.

```plantuml
@startsalt
scale 1.25
{
{T
 + <color:goldenrod><&folder></color> DeploymentFramework-//version//
 ++ <color:goldenrod><&folder></color> active_blades | <color:gray>Symbolic links to all active blades</color>
 +++ <color:silver><&folder> //bladename//</color> | <color:cyan><&share></color><color:gray> ../kits///bladename///Latest</color>
 ++ <color:goldenrod><&folder></color> doc
 ++ <color:goldenrod><&folder></color> global_config | <color:gray>Local deployment configuration</color>
 +++ <color:silver><&folder> dump</color>
 +++ <color:goldenrod><&folder></color> inactive_overrides
 +++ <color:goldenrod><&folder></color> licenses | <color:gray>Component licences</color>
 ++++ <color:silver><&file> license-rttpd.conf</color>
 ++++ <color:silver><&file> license-transformer.conf</color>
 +++ <color:goldenrod><&folder></color> overrides  | <color:gray>Local configuration overrides</color>
 ++++ <color:goldenrod><&folder></color> servers
 +++++ <color:goldenrod><&folder></color> Liberator
 ++++++ <color:goldenrod><&folder></color> etc
 +++++ <color:goldenrod><&folder></color> Transformer
 ++++++ <color:goldenrod><&folder></color> etc
 ++++ <color:silver><&folder> //bladename//</color>
 +++++ <color:silver><&folder> etc</color>
 +++++ <color:silver><&folder> Liberator</color>
 ++++++ <color:silver><&folder> etc</color>
 +++++ <color:silver><&folder> Transformer</color>
 ++++++ <color:silver><&folder> etc</color>
 +++ <color:goldenrod><&folder></color> ssl | <color:gray>Liberator TLS key and certificate</color>
 ++++ <color:silver><&folder> rttpd-https.pem</color>
 ++++ <color:silver><&folder> rttpd-https.key</color>
 ++++ <color:silver><&folder> rttpd-https.pwd</color>
 +++ <color:red><&ban></color> activeblades.txt | <color:gray>System file</color>
 +++ <color:red><&ban></color> bootstrap.conf | <color:gray>System file</color>
 +++ <color:cornflowerblue><&cog></color> environment.conf | <color:gray>Local variable overrides</color>
 +++ <color:red><&ban></color> environment-defaults.conf | <color:gray>System file</color>
 +++ <color:cornflowerblue><&cog></color> fields.conf | <color:gray>Local field definitions</color>
 +++ <color:red><&ban></color> hosts.conf | <color:gray>System file</color>
 +++ <color:red><&ban></color> hosts-defns.conf | <color:gray>System file</color>
 ++ <color:goldenrod><&folder></color> kits
 +++ <color:goldenrod><&folder></color> archive
 +++ <color:silver><&folder> //bladename//</color>
 ++++ <color:silver><&folder> Latest</color> | <color:cyan><&share></color><color:gray> .///bladename-version//</color>
 ++++ <color:silver><&folder> //bladename-version//</color>
 +++++ <color:silver><&folder> bin</color>
 +++++ <color:silver><&folder> doc</color>
 +++++ <color:silver><&folder> etc</color>
 +++++ <color:silver><&folder> lib</color>
 +++++ <color:silver><&folder> var</color>
 +++ <color:cornflowerblue><&script></color> bootstrap.sh | <color:gray>System script</color>
 ++ <color:goldenrod><&folder></color> servers | <color:gray>Working directories for Liberator and Transformer</color>
 +++ <color:goldenrod><&folder></color> Liberator
 ++++ <color:goldenrod><&folder></color> bin |  <color:cyan><&share></color><color:gray> ../../kits/Liberator/Latest/bin</color>
 ++++ <color:goldenrod><&folder></color> doc |  <color:cyan><&share></color><color:gray> ../../kits/Liberator/Latest/doc</color>
 ++++ <color:goldenrod><&folder></color> etc |  <color:gray>Master configuration (do not edit)</color>
 ++++ <color:goldenrod><&folder></color> lib |  <color:cyan><&share></color><color:gray> ../../kits/Liberator/Latest/lib</color>
 ++++ <color:goldenrod><&folder></color> users 
 ++++ <color:goldenrod><&folder></color> var 
 +++ <color:goldenrod><&folder></color> Transformer
 ++++ <color:goldenrod><&folder></color> bin |  <color:cyan><&share></color><color:gray> ../../kits/Transformer/Latest/bin</color>
 ++++ <color:goldenrod><&folder></color> doc |  <color:cyan><&share></color><color:gray> ../../kits/Transformer/Latest/doc</color>
 ++++ <color:goldenrod><&folder></color> etc |  <color:gray>Master configuration</color>
 ++++ <color:goldenrod><&folder></color> lib |  <color:cyan><&share></color><color:gray> ../../kits/Transformer/Latest/lib</color>
 ++++ <color:goldenrod><&folder></color> var
 ++ <color:goldenrod><&folder></color> tools | <color:gray>System files</color>
 ++ <color:cornflowerblue><&script></color> dfw | <color:gray>CLI</color>
}
}
@endsalt
```

* **active_blades/**\
The Framework uses this directory to manage which blades are active.
* **dfw**\
A command-line interface (CLI) for managing the Framework and blades. You can perform any Framework operation by running the dfw utility with the appropriate command parameter.

  * To get a list of all the possible Framework commands, type: ./dfw help
  * To run a Framework command, type: ./dfw &lt;command>

  Also see the [list of dfw commands](cdf-the-deployment-framework-command-utility-dfw.md) on this web site.
* **doc**\
This directory contains documents about the Framework, and the associated release note.
* **global_config/**\
This directory holds files and directories concerning configuration that is global to the Framework. To customise the configuration, only change files that are in the global_config directory and its subdirectories. All other configuration files in the Framework and in Caplin supplied blades are read-only and must not be edited.
* **global_config/environment.conf**\
Defines configuration macros that are server specific, such as the port numbers of the core components and the location of the Java Runtime Environment (JRE). The default settings are defined in the included file _environment-defaults.conf._
* **global_config/hosts-defns.conf**\
Defines the servers that core components and any Adapter blades run on. You must update this file to reflect the deployment - you usually do this by running the Framework command [`./dfw hosts`](cdf-the-deployment-framework-command-utility-dfw.md#hosts). Note that an Integration Adapter blade consists of an executable binary file in addition to its configuration and core component configuration, so you need to define which server(s) its executable will run on.
* **global_config/fields.conf**\
A file that defines the names of global fields used in DataSource messages.
* **global_config/licenses/**\
When components are deployed, any licenses required by these components must be placed in this directory. The Liberator license must be named _license-rttpd.conf_, and the Transformer license must be named _license-transformer.conf_.
* **global_config/ssl/**\
Any SSL keys required by the system must be placed in this directory, including the public key file for Caplin KeyMaster.
* **global_config/overrides/**\
This directory contains files that you can update to change configuration; for example, to make the Liberator log events at DEBUG level instead of INFO level.
* **global_config/inactive_overrides/**\
When you [deactivate](cdf-activate-and-deactivate-blades.md) a blade, any configuration overrides that apply to it are moved from the _overrides_ directory to the _inactive-overrides_ directory. When you subsequently [activate](cdf-activate-and-deactivate-blades.md) the blade again, its configuration overrides are moved from _inactive-overrides_ back to _overrides_.
* **global_config/dump/**\
The default directory where configuration information created by the [`./dfw dump`](cdf-the-deployment-framework-command-utility-dfw.md#dump) command is located.
* **kits**\
This directory initially contains the Framework’s built-in Caplin Platform blades and some scripts:
* **kits/bootstrap.sh**\
Used on Windows to ensure that links in the kit are created correctly.

* **servers/**\
This directory holds configuration files containing server specific configuration for the core components.
* **tools/**\
This directory contains some Cygwin utilities that are used by the Framework scripts, and a utility script (_information.sh_) used by the built-in blades.

## Modular configuration

A key feature of the Deployment Framework is the modularisation of configuration. Each DataSource component is deployed to the framework as a blade containing the application binary and configuration for itself, Liberator (optional), and Transformer (optional).

When you start a DataSource application under the Deployment Framework, it loads a configuration file from the `etc/` directory in its working directory.

**DataSource configuration files (working directories underlined)**

* Liberator: `#servers/Liberator#/etc/rttpd.conf`
* Transformer: `#servers/Transformer#/etc/transformer.conf`
* DataSource adapter: `#active_blades/__bladename__/DataSource#/etc/datasouce.conf`

Each of the configuration files above use the file-inclusion directive [`include-file`](../datasource/datasource-configuration-syntax.md#including-multiple-configuration-files) to include a series of configuration files from the Deployment Framework and, in the case of Liberator and Transformer, other active blades.

By deploying ([`dfw deploy`](cdf-the-deployment-framework-command-utility-dfw.md#deploy)) and deleting ([`dfw delete`](cdf-the-deployment-framework-command-utility-dfw.md#delete)) components, and by activating ([`dfw activate`](cdf-the-deployment-framework-command-utility-dfw.md#activate)) and deactivating ([`dfw deactivate`](cdf-the-deployment-framework-command-utility-dfw.md#deactivate)) configuration blades, you move configuration into and out of two key Deployment Framework directories: `active_blades` and `global_config/overrides`. Liberator and Transformer’s configuration files contain wildcard file inclusions to include configuration from these two directories:

**Liberator wildcard file inclusion**

* `active_blades/*/Liberator/etc/rttpd.conf`
* `global_config/overrides/*/Liberator/etc/rttpd.conf`

**Transformer wildcard file inclusion**

* `active_blades/*/Transformer/etc/transformer.conf`
* `global_config/overrides/*/Transformer/etc/transformer.conf`

The following diagrams illustrate the chain of configuration-file inclusion when you run a component in the Deployment Framework. For information on how to dump the full configuration chain for a component, see the Deployment Framework command [`dfw dump`](cdf-the-deployment-framework-command-utility-dfw.md#dump).

Files and directories that a server administrator can customise at deployment time are shown in green. All other files and directories are either internal to the Deployment Framework or internal to a DataSource application.

**Liberator configuration file-inclusion chain**

```plantuml
@startmindmap
* servers/Liberator/etc/rttpd.conf
** global_config/bootstrap.conf
***[#LightGreen] global_config/environment.conf
**** global_config/environment-defaults.conf
*** global_config/hosts.conf
**[#LightGreen] licenses/license-rttpd.conf
** servers/Liberator/etc/fields.conf
*** global_config/bootstrap.conf
****[#LightGreen] global_config/environment.conf
***** global_config/environment-defaults.conf
**** global_config/hosts.conf
*** global_config/fields.conf
*** active_blades/*/blade_config/fields.conf
** active_blades/*/Liberator/etc/rttpd.conf
**[#LightGreen] global_config/overrides/*/Liberator/etc/rttpd.conf
** servers/Liberator/etc/java.conf
*** global_config/bootstrap.conf
****[#LightGreen] global_config/environment.conf
***** global_config/environment-defaults.conf
**** global_config/hosts.conf
*** active_blades/*/Liberator/etc/java.conf
***[#LightGreen] global_config/overrides/*/Liberator/etc/java.conf
** servers/Liberator/etc/cluster.conf
*** global_config/bootstrap.conf
****[#LightGreen] global_config/environment.conf
***** global_config/environment-defaults.conf
**** global_config/hosts.conf
*** active_blades/*/Liberator/etc/cluster.conf
***[#LightGreen] global_config/overrides/*/Liberator/etc/cluster.conf
@endmindmap
```

**Transformer configuration file-inclusion chain**

```plantuml
@startmindmap
* servers/Transformer/etc/transformer.conf
** global_config/bootstrap.conf
***[#LightGreen] global_config/environment.conf
**** global_config/environment-defaults.conf
*** global_config/hosts.conf
**[#LightGreen] licenses/license-transformer.conf
** servers/Transformer/etc/fields.conf
*** global_config/bootstrap.conf
****[#LightGreen] global_config/environment.conf
***** global_config/environment-defaults.conf
**** global_config/hosts.conf
*** global_config/fields.conf
*** active_blades/*/blade_config/fields.conf
** active_blades/*/Transformer/etc/transformer.conf
**[#LightGreen] global_config/overrides/*/Transformer/etc/transformer.conf
** servers/Transformer/etc/java.conf
*** global_config/bootstrap.conf
****[#LightGreen] global_config/environment.conf
***** global_config/environment-defaults.conf
**** global_config/hosts.conf
*** active_blades/*/Transformer/etc/java.conf
***[#LightGreen] global_config/overrides/*/Transformer/etc/java.conf
** servers/Transformer/etc/cluster.conf
*** global_config/bootstrap.conf
****[#LightGreen] global_config/environment.conf
***** global_config/environment-defaults.conf
**** global_config/hosts.conf
*** active_blades/*/Transformer/etc/cluster.conf
***[#LightGreen] global_config/overrides/*/Transformer/etc/cluster.conf
@endmindmap
```

**DataSource adapter configuration file-inclusion chain**

```plantuml
@startmindmap
* active_blades///bladename///DataSource/etc/datasource.conf
** global_config/bootstrap.conf
***[#LightGreen] global_config/environment.conf
**** global_config/environment-defaults.conf
*** global_config/hosts.conf
** active_blades///bladename///DataSource/blade_config/fields.conf
** global_config/fields.conf
**[#LightGreen] global_config/overrides///bladename///etc/datasource.conf
@endmindmap
```