Kwatee User Guide version 2.3.0

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

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 (import release bundle artifacts) 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 (edit artifact) icon brings up the artifact configuration panel for the selected artifact.

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

Artifact Configuration

artifact

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 (edit version) icon brings up the version configuration panel for the selected version.

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.

Note: version 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

version

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)

Note: if no platform is checked the version is assumed to be universal, that is, compatible with any platform.
Note: versions that are referenced in tagged releases cannot be modified except for their description and their disable state.

Deployment Actions can be defined 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.

Note: the working directory is set to the artifact deployment directory when an action is executed.

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

Note: 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

Clicking the (upload package) icon brings up the version package upload dialog.
Note: 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 (examine package contents) icon 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 (edit executable) icon brings up the version executable panel for the selected executable.

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

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.

Note: 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 package

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 the (view file contents) icon displays the content of the file.

Clicking the (download file) icon downloads the selected file.

Clicking the (edit special options) icon brings up the file options panel.

Clicking the (remove overlay) icon removes the selected overlay file (see package overlays).


IconDescription
fileRegular file
fileTemplate file (contains Kwatee variables)
fileOverlay file
fileOverlay template.
fileSpecial file (user-defined options). Can be found in combination with any of the above.

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

version package 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.

Special Files Locator

version package special files

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

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 (edit variable) icon brings up the version variable editor and lets you modify the variable's default value.

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

Clicking the (view variable references) icon displays all the references to that variable.

Version Executable

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:

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

release 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 in the following order of 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

Then there are system 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

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 (edit server) icon brings up the server configuration panel for the selected server.

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

Common Server Configuration

server

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:

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.

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.

Note: the same credentials will be used for each instance.

Manual Server Pool

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.

Note: only active instances will be retrieved.

Environments

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 the (edit environment) icon brings up the environment configuration panel for the selected environment.

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

Environment Configuration

environment

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 the (edit release) icon brings up the release panel.

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

Release Configuration

release

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 (download release bundle) icon lets you downloaded a release bundle which may be used to transfer release artifacts from one instance to another or to be used with the CLI installer.

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

Clicking the (tag release) icon (snapshot only) 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 copies the tagged configuration into the snapshot release.

Deployment Actions

Kwatee lets you define 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.

Note: 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:

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 (SKETCH).

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.
Note: 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.

Clicking the (substitute server) icon lets you select an environment server that is compatible with the versions (platform-wise) configured on the selected server. All artifacts and related variable definitions are moved to the new server.

Release variables

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 the (create variable) icon brings up to release variable editor and creates a new deployment variable from an undefined version variable reference.

Clicking the (edit variable) icon brings up to release variable editor to edit the current variable.

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.

Note: 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:

IconDescription
fileEnvironment artifact overlay file.
fileEnvironment artifact overlay template.
fileServer artifact overlay file
fileServer artifact overlay template
fileAny of the above can be combined with special file options.

Deployments

deployments

This panel lists all environments that are ready for deployment. Thas is, they contain at least one release that has no missing kwatee variables.

Clicking the (manage release) icon brings up the Deployment panel.

Deployment

deployment

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

The deployment operation can be be applied to either:

Clicking the (edit release) icon brings up the release panel.

Clicking the (deploy release) icon initiates a deploy operation and brings up the deployment status panel.

Clicking the (undeploy release) icon initiates an undeploy operation and brings up the deployment status panel.

Clicking the (check release integrity) icon initiates a start operation and brings up the deployment status panel.

Clicking the (start release executables) icon initiates a stop operation and brings up the deployment status panel.

Clicking the (stop release executables) icon initiates a status operation and brings up the deployment status panel.

Clicking the (check release executables status) icon initiates an integrity check operation and brings up the deployment status panel.

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

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.


StatusDescription
statussuccess
statusfailure
statusUndefined result - usually a sign that actions have not returned an understandable kwatee status code
statuscanceled
statusin progress
statusrunning - this status only occurs in status check operations
statusstopped - this status only occurs in status check operations
statuspending - not yet started
statusnot applicable - the operation does not apply to this artifact; for instance, a start operation is requested but there is not start action configured for the artifact version

Clicking the (view details) icon brings up a dialog that provides detailed status.

Clicking the (abort operation) icon returns to the deployment panel.

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

my account

System Properties

System properties

Kwatee Parameters

Application 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