Kwatee User Guide version 4.0.2

Introduction

Kwatee Agile Deployment is an application that manages the deployment and update of software on target servers. This user guide describes Kwatee's web interface; it is still very raw but it is the authors hope that the concepts presented herein will complement Kwatee's rather straightforward web interface. Nevertheless, should some concepts remain too obscure to be put into practice, do not hesitate to contact our support for clarifications and suggestions as to which parts of this reference manual are most wanting.

Kwatee uses the following terminology for its key elements:

ElementDescription
ArtifactAn artifact is an abstract designations of a deployable asset. Artifacts can contain one or more versions (see below).
VersionA version is an instance of an artifact that may represent a platform-specific package (see below) and/or a specific revision.
PackageThis term denotes the set of physical files to be eventually deployed, bundled as a single file. Kwatee recognizes the internal structure of .zip, .tar, .tar.gz, .tgz, .tar.bz2 and .war package formats that will be expanded on the target servers upon deployment.
TemplateA template is a file that contains Kwatee variables that will be instantiated upon deployment on target servers.
OverlayOverlays are files that are layered on top of the one of an existing package. They enable advanced configuration without altering original packages.
ServerServers, or rather target servers denote the network locations on which artifacts will be deployed.
Server PoolServer pools are seen as a single logical unit from a high-level deployment perspective but actually stand for a set of instances on which each deployment operation applied to the entire pool is individually applied.
EnvironmentAn environment defines a the working context of deployment operations. Environments associate servers with artifacts. A environment may contain several releases (see below).
ReleaseA release defines the artifact version that must be deployed on target servers within an environment. The reserved snapshot release is the only release that may be edited. All other releases are frozen versions of earlier configurations.
Deployment OperationDeployment operations generally denote operations performed on target servers which include: deploy, undeploy, integrity check, start, stop and runtime status.

Artifacts

Artifacts are abstract designations of software packages or files. An artifact is a generic denomination that is independent of the implementations which may available for different platforms in different versions.

Clicking the (create artifact) icon prompts for a artifact name then brings up the artifact configuration panel. The name serves as a reference and cannot be modified after the artifact is created. Artifact names may contain only alpha-numerical characters, '.' (dot) or '_' (underline).

Clicking the (delete artifact) icon deletes the selected artifact. Artifacts cannot be deleted as long as they are referenced by a release.

Clicking an artifact's name brings up the artifact configuration panel for the selected artifact.

Artifact Configuration

Artifacts can be Disabled so that they are excluded from deployment operations. Disabling an artifact is the only alternative to deleting it when it is referenced in frozen releases.

Artifacts contain Versions which describe specific implementations of physical packages.

An optional Description may be provided. Artifact descriptions only appear in user interface panels for informational purposes.

Clicking the (create version) icon prompts for a version name then brings up the version configuration panel. The name serves as a reference and cannot be modified after the artifact is created. Version names may contain only alpha-numerical characters, '.' (dot) or '_' (underline).

Clicking the (duplicate version) icon prompts for a version name then makes a copy of the selected version (package included) and brings up the version configuration panel.

Clicking the (delete version) icon deletes the version. Versions cannot be deleted as long as they are referenced by a release.

Clicking a version's name brings up the version configuration panel for the selected version.

Versions often have extensive configuration. The recommended procedure for creating a new version in an artifact is to duplicate the latest version. In most cases, only a new package will need to be uploaded.

Version Configuration

Versions are specific artifact implementations that define platform-dependent physical packages, version actions and executables. Versions can be Disabled so that they are excluded from deployment operations. Disabling a version is the only alternative to deleting it when it is referenced in frozen releases.

An optional Description may be provided. Version descriptions only appear in user interface panels for informational purposes.

Versions must define the Platforms they are compatible with. When configuring a release only compatible versions may be associated to a particular target server. Currently, Kwatee supports the following platforms: Linux (x86/64bits), Solaris (x86/sparc), Windows, AIX (experimental), MacOS X (x86)

1. If no platform is checked the version is assumed to be universal, that is, compatible with any platform.
2. Versions that are referenced in tagged releases cannot be modified except for their description and their disable state.

Clicking the (version deployment actions) let's you configure actions during the deployment process (see below).

Clicking the (upload package) icon brings up the version package upload dialog.

It is possible to define versions that have no packages. This is only useful if version actions are defined as these actions will be executed regardless of the existence of an package.

Clicking the (version variables) icon brings up the version variables panel.

Clicking the package's name (if there is a package) brings up the version package panel.

Clicking the (add executable) icon prompts for an executable name and brings up the version executable panel.

Clicking the (delete executable) icon deletes the selected executable.

Clicking an executable's name brings up the version executable panel for the selected executable.

Version Deployment Actions

Version deployment Actions are executed at different stages of the deployment process. Actions are user-defined shell scripts that will be executed on the target server.

  • Pre-deploy: this action is executed before an package is deployed on a target server.
    Use for checking installed pre-requisites, running database schema upgrade scripts, etc.
  • Post-deploy: this action is executed after an package has been deployed on a target server.
    Use to setup registry entries, configure crontab jobs, etc.
  • Pre-undeploy: this action is executed before an package is undeployed from a target server.
    Use to make sure processes are properly stopped (or stop them), etc.
  • Post-undeploy: this action is executed after an package has been undeployed from a target server.
    Use for deleting non-package data files, remove registry / crontab entries, etc.
The working directory will be set to the deployment directory when an action is executed.

Version deployment action scripts, when defined, are expected to return well-known results that are understandable by kwatee:

  • The literal [kwate_ok] if the script execution was successful
  • The literal [kwatee_error] followed by an optional message on the same line in case of error
  • Otherwise, status will be reported as undetermined
Version actions will be executed even if the version does not have an package. This feature may be useful to execute setup/cleanup operations without having to create a dummy package.

Actions must not necessarily be limited to a single shell script line. Typing the Enter key when editing an action will bring up the multi-line action editor

Package Upload

The version package contains the set of files to be eventually deployed on target servers. Any file can be uploaded as an package and will be copied into the repository.

Packages can be either uploaded or imported. The difference lies in that uploaded packages are sent to Kwatee via the browser's HTTP upload mechanism whereas imported packages must reside on the same file system on which Kwatee is installed and generate no network traffic. Kwatee's key benefits derive from it's ability to customize individual files within packages.

When uploading an updated package, pre-existing overlays and special file options may be preserved or erased depending on the value of the Delete existing version overlays checkbox.

Several package types are recognized based on their file extensions
ExtensionTypeComments
.zipZip packageInternal structure is browsable and customizable. Any level of compression should be supported
.tarTar packageInternal structure is browsable and customizable (tested with gnu Tar). This format preserves symbolic links and executable flags.
.tar.gz or .tgzGzipped Tar packageSee Tar packages
.tar.bz2Bzipped Tar packageSee Tar packages
.warWeb applicationsInternal structure is browsable and customizable.
DirectoryDirectoryAll files and sub-directories are recursively imported (only in import mode).
otherGeneric fileTreated as a plain (and opaque) file.
When uploading a new package it is usually best not to check the Delete existing overlays check box so that existing special files options are preserved along with earlier overlays.

Package Customization

Version packages can be customized by overlaying additional files and by setting options files that need special treatment.

Clicking the (add overlay) icon lets you upload/import an overlay file (see package overlays).

Clicking the (special files) icon brings up the Special Files Locator dialog.

Clicking the (variable prefix character) icon brings up the Change Version Package Variable Prefix dialog.

Clicking a file's name brings up the file options panel.

Package Overlays

It is possible to add single files to an package; these files are called overlays. The version overlay mechanism enables the usage of off-the-shelf third party packages with all the benefits of Kwatee management and customization.

The Destination Path specifies at which relative path of the package the overlay will be uploaded (or imported). The Destination Path will be pre-filled with the path of the current selection in the package file tree but can be modified manually to any value, regardless of whether it already exists in the package or not.

If an overlay has the exact same name than that of an existing file in the package it will override that file. This feature is useful, for instance, for replacing a file containing hard-coded parameters with a template file containing kwatee variables that can be defined later on a per-release basis.

File Options

Some files in an package may require non-standard handling due to their special nature.

This non-standard handling can be configured with the special options dialog.

Ignore during integrity check: some application require files at installation which get modified by the application itself during its lifetime, or files that must be deleted at the end of the installation. To prevent such files from triggering an unwanted integrity check report, this option may be checked.

Ignore Kwatee variables: there are cases where regular files contain data that get unintentionally interpreted as Kwatee variables. To avoid such files to be treated as templates check this option.

Don't remove when uninstalling: there may be cases where a file in an artifact should survive artifact undeployment. To prevent such a file from being removed check this option.

Clicking the (file permissions/ownership) icon let's you configure the owner/group of the file or directory as well as the reading and writing permissions.

File permissions will only be applied if the target server to which they are deployed is configured with the Use sudo when deploying option.

Special Files Locator

The special files locator lists all overlay files, files with kwatee variables or files that have options. Selecting a file in the list and clicking the Find button expands the parent directories in the package tree and selects the file.

Change Version Package Variable Prefix

There are cases where %{text} pattern is used within version package files and should not be interpreted as a kwatee variable. Variable detection can be turned off in these files using the Special File options. However, this can be a tedious operation when there are many such files. Also, it may be required to have actual kwatee variables in these files as well. To address this problem, kwatee enables you to customize the pattern that it uses to detect kwatee variables in file. This customization is limited to modifying the first characer of the patter; so, instead of the default %{varName} you could use &{varName} instead. The pattern may be customized on a version per version basis. The custom variable prefix only affects kwatee variable detection within version package files (or overlays). Other kwatee variable references found in actions are unaffected.

Version Variables

This panel lists all kwatee variables that occur either in version package files or in version actions. It is possible but not mandatory to define default values for the version's kwatee variables.

Clicking the (add variable) icon brings up the version variable editor and lets you create a new variable.

Clicking the (undefine variable) icon removes the variable if it manually created. Otherwise it just clears the previously set default value.

Clicking a variable's name brings up the version variable editor and lets you modify the variable's default value.

Version Executable

The version executable configuration defines the shell commands to start, stop and query the status of an application. The version executable is an optional configuration that is useful only if the package represents an application/service or web application. More than one executable may be configured for the discrete management and status of applications made up of several collaborative components.

An optional Description may be provided. Executable descriptions only appear in user interface panels for informational purposes.

Start action is the shell script that will be invoked during a start operation.

Stop action is the shell script that will be invoked during a stop operation.

Status action is the shell script that will be invoked during a status operation.

Executable action scripts, when defined, are expected to return well-known results that are understandable by kwatee:

Expected script results
ActionExpected output
Start
  • The literal [kwatee_running] if the executable was successfully launched
  • The literal [kwatee_error] in case of error
  • Otherwise, status will be reported as undetermined
Stop
  • The literal [kwatee_stopped] if the executable was successfully stopped
  • The literal [kwatee_error] in case of error
  • Otherwise, status will be reported as undetermined
Status
  • The literal [kwatee_running] if the executable is running
  • The literal [kwatee_stopped] if the executable is stopped
  • The literal [kwatee_error] in case of error
  • Otherwise, status will be reported as undetermined

Actions are not limited to a single shell script line. Typing the Enter key when editting an action will bring up the multi-line action editor

Kwatee Variables

Kwatee variables have the pattern %{variableName} where variableName must be made up of alpha-numerical characters and start with a letter. There are built-in variables such as %{kwatee_package_dir} and custom ones that you can make up such as %{myservice_port}.

There are cases where %{text} pattern is used within version package files and should not be interpreted as a kwatee variable. Variable detection can be turned off in these files using the Special File options. However, this can be a tedious operation when there are many such files. Also, it may be required to have actual kwatee variables in these files as well. To address this problem, kwatee enables you to customize the pattern that it uses to detect kwatee variables in version package files using the Change Package Variable Prefix function. The custom variable prefix only affects kwatee variable detection within version package files (or overlays). Other kwatee variable references found in actions are unaffected.

It is possible to configure kwatee to fully ignore kwatee variables in files with specific extensions when scanning packages by configuring the Administration Parameters. Properly defining these extension blacklists will also improve performance when uploading large packages.

Kwatee variables definitions may optionally define default values using the special syntax: %{variableName=defaultValue}. Upon importing packages containing such patterns, kwatee will automatically create a default value entry.

Variable Editor

Variables values can be any literals and may contain reference to other variables or system properties.

Variable values have scopes and multiple values may be defined for the same variable at different scopes. Scopes override each other from the general to the more specific.

Scopes override precedence
ArtifactServerScopeDescription
AnyAny- all -the value is applicable for any artifact in any server of the release
AnyserverNameall artifacts@serverNamethe value is applicable for all artifacts in a given server.
artifactNameAnyartifactName in all serversthe value is applicable to a given artifact in any server.
artifactNameserverNameartifactName@serverNamethe value is applicable to a specific artifact in a specific server. Nothing has a higher precedence than this.

Overriding is a powerful feature of deployment variables which provides a great deal of flexibility in configuration. For instance, the deployment paths of Kwatee artifacts on target servers can be customized by overriding system properties. By default, Artifacts are installed at kwatee_package_dir which resolves to:

kwatee_package_dir=%{kwatee_deployment_dir}/%{kwatee_package_name}

and

kwatee_deployment_dir=/var/tmp/kwateetest/%{kwatee_environment_name}

In the case of a tomcat web application wars must be deployed to tomcat's webapps directory.
This is achieved by overriding kwatee_deployment_dir=/usr/local/tomcat/webapps.

There are a few built-in variables that cannot be overriden
VariableDescription
kwatee_environment_nameEnvironment name in whose context the deployment operation or action is running
kwatee_release_nameRelease name in whose context the deployment operation or action is running
kwatee_package_nameArtifact name in whose context the deployment operation or action is running
kwatee_server_nameName of target server on which deployment operation or action is running
kwatee_server_ipIP address of target server on which deployment operation or action is running
kwatee_server_instanceName of a server pool instance
Overridable system variable that define properties needed in deployment operations
PropertyDescription
kwatee_root_dirThis is the directory in which Kwatee will install the required kwagent executable. It is advisable to have only one kwatee_root_dir per server
kwatee_deployment_dirThis variable is only used to construct the kwatee_package_dir (see below) for the default installation hierarchy. The default value is used only for demo purposes. It should be redefined or overriden.
kwatee_package_dirThis is the directory in which a target artifact will get deployed. By default that directory resolves to: /var/tmp/kwateetest/environmentName/artifactName but you can redefine it to any absolute path you wish. Make sure that the underlying SSH user has proper privileges to write and modify this directory.

Servers

A kwatee server entry must be defined for each target server on which software is to be deployed on. Kwatee also supports server pools which are seen as a single logical entity but that contain several physical instances.

Clicking the (create server) icon prompts for a server name then brings up the server configuration panel.

Clicking the (create server pool) icon prompts for a server pool name and the type of server pool to create then brings up the server configuration panel. Currently two server pool types are supported: manual server pools and Amazon EC2 server pools. Once created, the server pool type cannot be changed. In both cases the name serves as a reference and cannot be modified after the server is created. Server names may contain only alpha-numerical characters, '.' (dot) or '_' (underline).

Clicking the (delete server) icon deletes the selected server. Servers cannot be deleted as long as they are referenced by a release.

Clicking a server's name brings up the server configuration panel for the selected server.

Common Server Configuration

Servers can be Disabled so that they are excluded from deployment operations. Disabling a server is the only alternative to deleting it when it is referenced in frozen releases.

An optional Description may be provided. Server descriptions only appear in user interface panels for informational purposes.

Platform is a mandatory parameter. Kwatee currently supports Linux, Solarix, AIX, Windows and MacOS target platforms. This parameter determines which Kwatee agent will be installed as well as the compatibility with versions.

An appropriate Remote access type, such as it is supported by the remote server, must be selected.

Remote access types
Access TypeDescription
Secure Shell / Scp This is the prefered access type to be used whenever possible. Ssh remote access supports two modes of authentication: password or private key. Clicking the Has private key check box brings up the PEM dialog box where the private key can be entered. In that case, the password field becomes the paraphrase for the private key.
When the server platform is windows the Cygwin checkbox is shown. This option must be checked for ssh implementations based on cygwin such as OpenSSH.
Telnet / ftp
server telnet
Telnet / FTP is an experimental access type that is intended mainly for windows servers if usage of built-in services is prefered over the installation of third-party Ssh implementations. Advanced Options are available for the personalization of the telnet login & password prompts which are necessary for the telnet operation, as well as the definition of non-standard FTP ports. Telnet remote access works by simulating a user login. This requires knowledge of the prompts identifying the login and the password inputs. The defaults are Login: for the Login prompt and Password: for the Password prompt. Non-standard FTP ports may also be customized in the Telnet Options.

Login is the user id for logging into ssh or telnet & ftp. Password is the password for logging into ssh or telnet & ftp, unless Has private key has been checked in ssh mode in which case the password is used as the paraphrase for the provided private key. Checking the Prompt checkbox will cause the user to be prompted for the password when launching an operation.

Regular servers (as opposed to server pools) reference exactly one physical target server. Their definition includes an IP Address which can be provided either in dotted IP or domain name form, and a Port to be used for the ssh or the telnet connection.

The Use sudo when deploying option must be checked if your deployment operations require elevated privileges.

Remember to add a sudoers entry with NOPASSWD for kwagent.

Server Pools

Server pools act as a single logical unit from a configuration perspective in terms of artifact and version definition, configuration and variable instantiation. Each deployment operation will be executed identically on each instance of the pool.

Concurrency is a common parameter to all server pools and determines how many server pool instances can execute deployment operations in parallel. Possible values are one at a time, two at a time, five at a time or maximum. Maximum is good for updating an internal pool of servers where up-time is not a consideration. On live public sites, depending on the size of the pool and the level of traffic a lower concurrency is recommended.

The same credentials will be used for each instance.

Manual Server Pool

The manual server pool lets you define each instance parameter in the pool manually. Each deployment operation in which the server pool is involved will be replicated on all of its instances. Instances can are manually created and must be assigned a unique IP address and port.

The instance name is mandatory but only serves for informations purposes.

Amazon EC2 Server Pool

The Amazon Elastic Cloud server pools let you define dynamic criteria to select qualifying EC2 instances. An AWS Access Key Id must be provided as well as the Secret key to gain access to the AWS API. EC2 pools provide three ways to select instances:

  1. Load Balancer selects all the instances associated to the AWS load balancer identified by the value of the Select field group. Load balancer-based EC2 pools have a special behavior: before a deploy or undeploy action, the instance will be removed from the EC2 load balancer and will be re-inserted at the end of the operation.
  2. AMI Id selects all the instances that are based on the same AMI Id identified by the value of the select field group.
  3. Security Group selects all the instances that are in the security group identified by the value in the select field group.
Only active instances will be retrieved.

Environments

Environments define the set of artifacts and servers that are available for releases.

Clicking the (create environment) icon prompts for an environment name then brings up the environment configuration panel. The name serves as a reference and cannot be modified after the environment is created. Environment names may contain only alpha-numerical characters, '.' (dot) or '_' (underline).

Clicking (delete environment) icon deletes the selected environment and all its releases.

Clicking an environment's name brings up the environment configuration panel for the selected environment.

Environment Configuration

Environments associate a set of environment servers with a set of environment artifacts.

An optional Description may be provided. Environment descriptions only appear in user interface panels for informational purposes.

There can be many releases in an environment but only one of them can be edited: snapshot. This release is meant to be used for work in progress.

Clicking the Edit snapshot button brings up the release panel.

Clicking the (add artifacts) icon brings up a dialog that lets you select existing artifacts to be added to this environment. Artifacts already included in the environment are not listed. Artifacts will be deployed on each server in the order listed on this panel and undeployed in the reverse order. Artifact deployment on a target server is never parallelized so ordering is always strictly enforced to make sure that artifacts down the line may rely on the presence of necessary pre-requisites.

Clicking the (move artifact up) icon moves the selected artifact up in the list.

Clicking the (move artifact down) icon moves the selected artifact down in the list.

Clicking the (remove artifact) icon removes the selected artifact from the environment. Removal will fail if the artifact is referenced in any release.

Clicking the (add servers) icon brings up a dialog that lets you select existing servers to be added to this environment. Servers already included in the environment are not listed. Deployment operation will be performed sequentially on each server in the order listed on this panel for deploy/start operations and in the reverse order for undeploy/stop operations if the Deploy in sequence is checked. Otherwise, the actual deployment sequence will be unpredictable as deployments on many servers will be parallelized.

Clicking the (move server up) icon moves the selected server up in the list.

Clicking the (move server down) icon moves the selected server down in the list.

Clicking the (remove server) icon removes the selected server from the environment. Removal will fail if the artifact is referenced in any release.

Clicking a release's name brings up the release panel.

Clicking the (delete release) icon deletes the selected release.

Release Configuration

Releases are defined within an environment and associate specific environment artifact versions to target environment servers. snapshot is a special release which is actually the only one that can be edited.

An optional Description may be provided

Clicking the (release permissions/ownership) icon let's you configure the default owner/group of all deployed files and directories as well as their default permissions.

Clicking the (edit / view release kwatee variables) icon brings up the Release Variables panel.

Clicking the (release deployment actions) let's you configure actions during the deployment process (see below).

Clicking the (tag release) icon, which is enable only for the snapshot release, prompts for a release name and then copies the snapshot configuration into the new frozen release. It is good practice to tag a release when it is ready for production. Since frozen releases are uneditable you can re-instantiate them in the future with the confidence that they will be identical to the time they were deployed in production.

Clicking the (reedit tag as snapshot) icon, which is enabled only for previously tagged releases, copies the tagged release back into the snapshot release.

Release Deployment Actions

Kwatee lets you define release deployment actions that will be executed at different stages of the deployment process. Actions are user-defined shell scripts that will be executed on the target server.

  • Pre-setup: this action is executed once per target server before any version is deployed. Use for checking installed pre-requisites, running database schema upgrade scripts, etc.
  • Post-setup: this action is executed once per target server after all the configured versions have been deployed on the server. Use to setup registry entries, configure crontab jobs, etc.
  • Pre-cleanup: this action is executed once per target server before any version is undeployed. Use to make sure processes are properly stopped (or stop them), etc.
  • Post-cleanup: this action is executed once per target server all the configured versions have been undeployed from the server. Use for deleting non-package data files, remove registry / crontab entries, etc.
The working directory will be set to the deployment directory when an action is executed.

Deployment action scripts, when defined, are expected to return well-known results that are understandable by kwatee:

  • The literal [kwate_ok] if the script execution was successful
  • The literal [kwatee_error] followed by an optional message on the same line in case of error
  • Otherwise, status will be reported as undetermined

Server Artifacts

The Server artifacts area provide the means to configure the versions to be deployed on environment servers and to customize them.

Each environment server is represented as a folder, in addition to the default versions folder which lists all the environment artifacts (white environment artifact icons denote artifacts not yet assigned in this release).

The toolbar options will be enabled depending on the type of element selected in the tree and whether the current environment is editable (SNAPSHOT).

Clicking the (change active version) icon lets you select a version for the artifact that is assigned to the selected server. Setting the active version of an Environment Artifact will make that version the default for that artifact on all servers. Of course, the default can be overriden by selecting a different active version on a server artifact. A release will not be valid until all server artifacts have an active version.

If a default Environment Artifact version is not platform compatible with a server where it is installed, the default must be overriden with a suitable version.

Clicking the (add/remove overlays) icon brings up the Release Overlays panel.

Clicking the (add artifact to server) icon lets you select environment artifacts to assign to the selected server.

Clicking the (remove artifact from server) icon removes the selected artifact from its server. This operation will not trigger an undeploy operation so if the artifact was previously installed on the server it should be undeployed first.

Release variables

This panel let's you assign values for kwatee variables.

All variables occuring in a release must be assigned before it can be deployed.

Clicking the (add variable) icon brings up to release variable editor and creates a new deployment variable.

Clicking a variable's name brings up to release variable editor to edit the current variable.

Clicking the (duplicate variable) icon let's you create a new variables by modifying selected properties of the current one.

Clicking the (delete variable) icon deletes the selected variable.

Overlays & Special File Options

Deployment overlays and special file options work exactly the same way as version overlays. Deployment overlays can be uploaded either to Environment Artifacts in which case they will be common to all servers containing that artifact, or they can be uploaded to server artifacts. If a server artifact overlay and an environment artifact overlay overlap, the server artifact overlay will take precedence. The same goes for special file options.

Special file options can be set only on overlays and in the context (environment artifact or server artifact) where they were uploaded.

When an active version is defined, the version package files will be shown in addition to the deployment overlays.

Two new file icons identify deployment overlays.

Deployments

This panel lists all environments that contain deployable releases. Releases that have errors will not be included.

Clicking a release's name brings up the Deployment panel.

Deployment

Possible deployment operations are: Deploy, Undeploy, Start, Stop, Status and Check Integrity.

The deployment operation can be be applied to either:

  • The entire release.
  • All artifacts on the selected server.
  • The selected environment artifact on all server that it is assigned to.
  • The selected artifact on the selected server.

Deploy Operation

The deploy operation installs version packages onto their target servers as per release configuration. Deploy operations are parallelized on multiple target servers unless the Deploy in sequence option was selected in the environment servers panel in which case servers are deployed one by one in the environment servers order. Artifact deployment order within a server is always enforced in Environment Artifact sequence order. The following operations will be executed on each target server during deployment:

Establish remote connection to server
Execute deployment pre-setup action
for each artifact in server do:
   Determine differential update set with respect to existing version
   If deployed version is not up-to-date then:
      Execute artifact pre-deploy action
      Copy differential update over to server
      Instruct kwateeAgent to expand differential update in artifact directory
      Execute post-deploy action
Execute deployment post-setup action
Close remote connection

Undeploy Operation

The undeploy operation uninstalls version packages from their target servers as per release configuration. Undeploy operations are parallelized on multiple target servers unless the Deploy in sequence option was selected in the environment servers panel in which case servers are undeployed one by one in the environment servers reverse order. Artifact undeployment order within a server is always enforced in Environment Artifact sequence reverse order. The following operations will be executed on each target server during undeployment:

Establish remote connection to server
Execute deployment pre-cleanup action
for each artifact in server do:
   Execute artifact pre-undeploy action
   Instruct kwateeAgent to remove all previously deployed artifact files
   Execute post-undeploy action
Execute deployment post-cleanup action
Close remote connection

Start Operation

The start operation starts all versions in the release that have executables defined with a start action. Start operations are parallelized on multiple target servers unless the Deploy in sequence option was selected in the environment servers panel in which case servers are started one by one in the environment servers order. Environment artifact order within a server is always strictly enforced. The following operations will be executed on each target server during start:

Establish remote connection to server
for each artifact in server do:
   for each executable in artifact do:
      Execute executable start action
Close remote connection

Stop Operation

The stop operation stops all versions in the release that have executables defined with a stop action. Stop operations are parallelized on multiple target servers unless the Deploy in sequence option was selected in the environment servers panel in which case servers are stopped one by one in the environment servers reverse order. Artifact stop order within a server is always enforced in Environment Artifact sequence reverse order. The following operations will be executed on each target server during stop:

Establish remote connection to server
for each artifact in server do:
   for each executable in artifact do:
      Execute executable stop action
Close remote connection

Status Operation

The status operation queries the runtime status from all versions in the release that have executables defined with a status action. Status operations are always parallelized on multiple target servers. The following operations will be executed on each target server during status check:

Establish remote connection to server
for each artifact in server do:
   for each executable in artifact do:
      Execute executable status action
Close remote connection

Integrity Check Operation

The integrity check operation verifies that artifacts previously deployed have not been tampered with, i.e., that installed package files are exactly as they were when deployed. Integrity check operations are always parallelized on multiple target servers. The following operations will be executed on each target server during integrity check:

Establish remote connection to server
for each artifact in server do:
   request kwateeAgent to perform integrity check
Close remote connection

Deployment Status

This panel shows the current status of ongoing deployment operations and then the final result. The list shows the status of each artifact deployment operation as well as the server's compounded status.

Clicking the status link brings up a dialog that provides detailed status.

Kwatee Command Line Installer

The Kwatee CLI Installer (kwclideployer) is a useful tool for performing field installations where remote access is disallowed or otherwise impractical. kwclideployer requires only a JRE; no application server or pre-configured database are used. It deploys the artifacts and configuration defined in a kwatee release bundle (see release).

The CLI Installer comes with a convenience shell script: kwdeploy.sh and accepts the following parameters:

usage: kwclideployer
    --artifact <name>       artifact name
    --cancel                cancel ongoing operation
    --check                 check release artifacts integrity
    --contents              show release details
    --deploy                install release artifacts
    --help                  print this message
 -P,--password <password>   kwatee password
 -R,--repo <path>           repository location
    --server <name>         server name
    --server-local <name>   server name
    --start                 start release artifacts executables
    --status                check release artifacts executables status
    --stop                  stop release artifacts executables
 -U,--user <user>           kwatee user
    --undeploy              uninstall release artifacts
    --undeploy-forced       uninstall release artifacts regardless of
                            errors

Administration

An email may be stored for users but it is not currently used by kwatee and may be left out.

System Properties

System properties a special kwatee variables that are common to all releases. You may change the global defaults here but it is also possible to override system variable values for a specific release, artifact or server.

Kwatee Parameters

You can personalize your kwatee instance by entering a Title value. This title will be displayed on all pages above the menu bar.

It is possible to configure kwatee to fully ignore kwatee variables in files with specific extensions when scanning packages by configuring the Exclude File Extensions for Variable Scanning.

Import / Export

Import/Export features may be used to keep backups of kwatee configuration. They can also serve to move a kwatee configuration from one server to another or from one database type to another.