Custom application descriptors

The Deployment Template installer is driven off of application descriptor XML documents that describe the directory structure associated with the deployment as well as the files to distribute during the installation process.

By default, the installer is shipped with application descriptor files for Agraph and Dgraph deployments powered by the EAC Development Toolkit (located in the conf subdirectory of the deploymentTemplate-[VERSION] install directory).

This document describes the directory structure of the deployment as well as the copying that is done during the installation to distribute files into the new directories. Additionally, this document describes whether files are associated with a Windows or UNIX deployment, and whether copied files should be updated to replace tokens in the format @@TOKEN_NAME@@ with text strings specified to the installer.

The following tokens are handled by the installer by default:

@@EAC_PORT@@ - EAC Central Server port.
@@HOST@@ - Hostname of the server on which the deploy script is invoked.
@@PROJECT_DIR@@ - Absolute path of the target deployment directory.
@@ESCAPED_PROJECT_DIR@@ - Absolute path of the target deployment directory using only forward slashes.
@@PROJECT_NAME@@ - Name of the application to deploy.
@@ENDECA_ROOT@@ - Absolute path of the ENDECA_ROOT environment variable.
@@SCRIPT_SUFFIX@@ - ".bat" for Windows, ".sh" for Linux installs.
@@SLASH@@ - "\" for Windows, "/" for Linux installs.
@@PARALLEL_FORGE_ENABLED@@ - "true" or "false," indicating whether parallel forge is enabled for the Agraph deployment.
@@WORKBENCH_ENABLED@@ - "true" or "false," indicating whether Workbench integration is enabled for the application.
@@WORKBENCH_PORT@@ - Oracle Endeca Workbench port.

In addition to these default tokens, users can specify custom tokens to substitute in their files. Tokens are specified in the application descriptor file, including the name of the token to substitute as well as the question with which to prompt the user or the installer configuration option to parse to retrieve the value to substitute for the token. The default application descriptors use this functionality to request the port number for Dgraphs, Agraphs, Log Servers and Forge servers.

Projects that deviate from the Deployment Template directory structure may find it useful to create a custom application descriptor document, so that the Deployment Template installer can continue to be used for application deployment.

Custom deployment descriptors may also be used to define add-on modules on top of a base install. For example, sample applications (such as the Sample Term Discovery and Clustering application) are shipped with a custom deployment descriptor file, which describes the additional files and directories to install on top of a base Dgraph deployment. Modules may be installed using the deploy batch or shell script, specifying the --app argument with the location of the application descriptor document. For example:

deploy.bat --app \
C:\Endeca\Solutions\sampleTermDiscovery-[VERSION]\data\deploy.xml

The installer prompts you to specify whether it should install the module as a standalone installation or if it should be installed on top of the base Dgraph deployment. Multiple add-on modules may be specified to the installer script, though only one of them may be a base install (that is, all but one of them should specify an attribute of update= "true").

The following excerpt from the Dgraph deployment application descriptor identifies the document's elements and attributes:

<!--
  Deployment Template installer configuration file. This file defines the directory structure to create and the copies to perform to distribute files into the new directory structure.

  The update attribute of the root install element indicates whether this is a core installation or an add-on module. When set to false or unspecified, the installation requires the removal of an existing target install directory (if present). When update is set to true, the installer preserves any existing directories, adding directories as required and distributing files based on the specified copy pattern.
-->
<app-descriptor update="false" id="Dgraph">

  <custom-tokens>
    <!-- Template custom token:
      <token name="MYTOKEN">
        <prompt-question>What is the value to substitute for token MYTOKEN?</prompt-question>
        <install-config-option>myToken</install-config-option>
        <default-value>My Value</default-value>
      </token>
      
      This will instruct the installer to look for the "myToken" option
      in a specified install config file (if one is specified) or to 
      prompt the user with the specified question to submit a value. If a
      value is entered/retrieved, the installer will substitute instances
      of @@MYTOKEN@@ with the value.
    -->
  </custom-tokens>

  <dir-structure>
    <!-- Template directory:
      <dir platform="unix" primary="true"></dir>
      
      primary           builds directory only on primary server installs
      
      platform          builds directory only on specified platform.
                          Valid values: "win" and "unix"
    -->  
  </dir-structure>
  
  <!—
  Copy source directory is specified relative to this file's directory 
  -->
  <copy-pattern src-root="../data ">
    <!-- Template copy pattern:
      <copy clear-dest-dir="true" recursive="true" 
            preserve-subdirs="true" filter-files="true" 
            primary="true" platform="win" Endeca-version="480">
        <src-dir></src-dir>
        <src-file></src-file>
        <dest-dir></dest-dir>
      </copy>

      src-dir           source directory, relative to root of deployment
                          template package.
      
      src-file          source filename or pattern (using '*' wildcard
                          character) to copy from source dir
      
      dest-dir          destination directory, relative to root of target
                          deployment directory.
            
      clear-dest-dir    removes all files in target dir before copying
      
      recursive         copies files matching pattern in subdirectories
                          of the specified source dir
      
      preserve-subdirs  copies files, preserving dir structure. Only
                          applicable to recursive copies
      
      filter-files      filters file contents and file names by replacing 
                          tokens (format @@TOKEN@@) with specified 
                          strings.
      
      mode              applies the specified permissions to the files 
                          after the copy. Mode string should be 3 octal 
                          digits with an optional leading zero to
                          indicate octal, e.g. 755, 0644. Not relevant
                          for Windows deployments.
      
      platform          applies copy to specified platform. Valid 
                          values: "win" "unix"
      
      Endeca-version    applies copy to specified Oracle Endeca version Valid 
                          values: "460" "470" "480" "500"
    -->
  </copy-pattern>
</app-descriptor>