Deploying an Apama application

The engine_deploy tool takes a project directory created using the apama_project tool and gets it ready for deployment in the correlator.

Usually this is by generating a correlator deployment directory containing a YAML configuration file with the initialization list (as described by Deploying Apama applications with a YAML configuration file). For advanced cases the tool can also:

generate an initialization file text list,
create a Zip file with the contents of the correlator deployment directory for copying to another machine,
generate a correlator deployment package (CDP),
perform the initialization into a running correlator.

Apama projects can be created with the apama_project tool or the Apama Extension for Visual Studio Code.

The engine_deploy tool can also be used with a directory of Apama files if you do not require support for bundles and do not plan to use the development tools mentioned above.

The executable for this tool is located in the Apama/bin directory.

Synopsis

To use this tool, run the following command:

engine_deploy action [options] path1 [path2...]

When you run this command with the –h option, the usage message for this command is shown.

Description

The action that you have to specify when you run this tool can be one of the following:

Action	Description
`-d dir \| zipfile` or `--outputDeployDir dir \| zipfile`	Specifies the deployment directory into which the project artifacts are to be copied and in which the YAML configuration files and properties files are to be created. You must not specify a subdirectory of the project directory as the deployment directory. Instead of a directory, you can also specify the name of a Zip file that is to be created (for example, `OutputDir.zip`) and which contains the same contents as the deployment directory. If you specify the name of an existing Zip file, this Zip file will be overwritten.
`--outputList file \| stdout`	Specifies where the initialization file list text file is to be created. This can be written either to a file or standard output. It is a simple format with one path per line.
`--outputCDP file`	Specifies the file name of the correlator deployment package (CDP) that is to be generated. The CDP is created using the correct injection order, and it contains any EPL files, Java EPL plug-in JAR files, event files and nested CDPs.
`--inject host port`	Specifies that each EPL file is to be injected into the correlator that is running on the specified host and port.

Only one action can be specified at a time.

Deployment directory

When you use this tool to generate a deployment directory, it copies all required files from the project into a deployment directory.

The deployment directory includes all of the project artifacts, except for log files, along with following generated files:

File name	Contents
`initialization.yaml`	List of all files that are to be loaded by the correlator at startup. See also Deploying Apama applications with a YAML configuration file. This file is always generated.
`initialization.properties`	Substitution variables for locations outside the project directory and `APAMA_HOME` used by `initialization.yaml`. This file is not generated for projects that use only initialization files from `APAMA_HOME` and the project directory.
`connectivity.yaml`	Connectivity configuration. This file is only generated when the input directory is an Apama project and when this project includes connectivity bundles.

After all output has been generated, you use the correlator executable with the --config option to start the correlator with all the YAML and properties files that have been generated. For example:

correlator --config ~/MyDeployDir

In addition to the generated .yaml files, any additional .yaml configuration files you provide at the top level of the project directory will be copied to the deployment output directory and read when the correlator is started. For example, you might add an arguments.yaml file to control where logs and other data files are written.

See Starting the correlator for detailed information on the available options.

If you want to override one or more property values that are defined in the generated properties files, you have to send an additional properties file containing these overrides (or you can set the property directly by specifying it on the command line) to the correlator before sending the generated properties files. For example, when you specify the following, the property values defined in the file myOverrides.properties will take precedence over all of the properties defined in other files.

correlator --config myOverrides.properties --config deployDir/

Important

If the project requires any JAR files for a Java EPL plug-in, you have to build the JAR files before you run engine_deploy.

Options

The engine_deploy tool takes the following options:

Option	Description
`--include pattern[,pattern]`	Specifies the files from the project that are to be included in the output/injection. For example: `*/foo/Bar.evt,**.mon` The command line `--include` filter is only applied after the tool has searched the directory tree for Apama files, so it cannot be used to avoid spending time recursively searching large subdirectories. See the note below on the `--exclude` argument for more information.
`--exclude pattern[,pattern]`	Specifies the files from the project that are to be excluded from the output/injection. For example: `*/foo/Bar.evt` Note: Log files are always excluded. The command line `--exclude` filter is only applied after the tool has searched the directory tree for Apama files, so it cannot be used to avoid spending time recursively searching large subdirectories. To do that, either use `apama_project config` to define which source subdirectories should be searched, or create an empty `.apamaignoredir` file in any part of the directory tree that should not be searched. For example, either approach could be used to avoid including testcase `.mon` files in your project.

Option

Description

--include pattern[,pattern]

Specifies the files from the project that are to be included in the output/injection. For example: **/foo/Bar*.evt,**.mon

The command line --include filter is only applied after the tool has searched the directory tree for Apama files, so it cannot be used to avoid spending time recursively searching large subdirectories. See the note below on the --exclude argument for more information.

--exclude pattern[,pattern]

Specifies the files from the project that are to be excluded from the output/injection. For example: **/foo/Bar*.evt

Note: Log files are always excluded.

The command line --exclude filter is only applied after the tool has searched the directory tree for Apama files, so it cannot be used to avoid spending time recursively searching large subdirectories. To do that, either use apama_project config to define which source subdirectories should be searched, or create an empty .apamaignoredir file in any part of the directory tree that should not be searched. For example, either approach could be used to avoid including testcase .mon files in your project.

Operands

path1 and other optional paths that you can specify when you run the engine_deploy tool can point to the following:

A project directory. This is the directory which contains the .project file and, if defined, the .dependencies file.

Note: You can only specify one project at a time. If a project references additional projects, then the generated injection order might not be accurate.

If you are not using the apama_project tool, you can specify any directory containing Apama files (for example, .mon files, etc.).
Zero or more .properties files which contain substitution variables that have been defined in the specified project. The properties files are used when you specify a project directory or deployment file. You can specify these paths in any order.
A text (.txt) file. This is the initialization file list which lists the project artifacts to be included.
One or more correlator deployment packages (.cdp files) to be injected into the correlator.

Examples

The following examples show the different ways in which the engine_deploy tool can be started.

Create an initialization list by pointing to a project directory containing the EPL files:
```
engine_deploy --outputList ~/apama_initialization_list.txt MyProject
```
Create a correlator deployment package by pointing to a deployment file within the project:
```
engine_deploy --outputCDP ~/output.cdp ~/MyDeployDir/MyProject
```
The correlator deployment package can then be injected into the correlator using engine_deploy or engine_inject.
Perform the initialization into a running correlator and excluding specific files from the injection:
```
engine_deploy --inject ~/MyDeployDir
   --exclude MyProject/somefiles/**
   MyProject
```
The --exclude option specifies that the generated deployment directory does not contain the files from the MyProject/somefiles directory, and that these files are also not to be used during injection.