Understanding the Application Package Structure

This topic will help you understand the structure of the .zpk package which contains the data, scripts, and an XML descriptor file for your application.

How do I prepare the application package?

How do I deploy the application package?

Package Structure

The .zpk package contains the following components:

Data

The application's main data directory for inclusion in the package. It contains the application files, deployment scripts, and extra resources such as icons, EULA and README (.txt/.md) files.

By default, this folder is called 'Data' but you can name it differently and reference it accordingly when building your package.

Descriptor File (deployment.xml)

This XML file, which is defined by an XSD file, describes all necessary information in order to deploy your application using Zend Server’s deployment feature, and contains:

type - The type of packaged application: PHP application or library.
name (Required) - The application/library name.
summary - The application short description.
description - The application long description.
version (Required) - The application version number.
releasedate - The application release date.
eula - The EULA file.
appdir - The applications directory. By default, this is the data folder of your package.
docroot - The alias will point to the directory you specify.
scriptsdir - The directory in which your scripts are located. By default, this is the scripts folder of your package.
healthcheck - Add the relative URLl you would like Zend Server to check against for Application Health Check. This checks if the URL returns a 200 (OK) response or an error response.
updateurl - The URL for updating applications.
dependencies - The dependencies that must be met (and will be validated) during the deployment process.
user parameters - The parameters for the deployment process. These, along with the values you define, will appear in the User Parameters dialog during deployment. For more information see Deploying an Application.
variables - Define environment variables for the deployment scripts.
persistent resources - Any files or directories you do not want removed from the server after removing or updating the application.

For an example of the descriptor template see The XML Descriptor File.

Scripts

Zend Server deployment consists of five actions: two for deployment, one for rollback and two for removal. Two hook scripts are provided for each action (pre and post), allowing you to customize the actions according to your needs. You can select from a list of available hook script constants to insert in the scripts.

Deploy:
- Stage - Place the contents of the .zpk application package on the server or on the cluster nodes.
  - Pre-stage - All customized actions that must be executed before the staging process begins.
  - Post-stage - All customized actions that must be executed after the staging process ends.
- Activate - Perform the final steps necessary to make a staged application public.
  - Pre-activate – All customized actions that must be executed before activation.
  - Post-activate - All customized actions that must be executed after activation.
Rollback:
- Rollback - Rolls back your application to the previous version.
  - Pre-rollback - All customized actions that must be executed before rollback.
  - Post-rollback - All customized actions that must be executed after rollback.
Remove:
- Deactivate - Deactivates the application on your server.
  - Pre-deactivate - All customized actions that must be executed before deactivation.
  - Post-deactivate - All customized actions that must be executed after deactivation.
- Un-stage - Cleans up your server and deletes any files that were relevant only to the now deactivated application.
  - Pre-unstage - All customized actions that must be executed before the un-staging process begins.
  - Post-unstage - All customized actions that must be executed after the un-staging process is completed.

See Preparing the Package Using the Deployment Tool to learn how to build your application package.

Monitoring and Caching Rules .xml Files

The Scripts component in the .zpk package can also include .xml files representing monitoring or caching rules. See Creating the Package to learn how to insert rules in your application package.

Hook Script Examples

The following is a list of examples for operations that may be defined in each hook script:

Pre-stage - Validate and applying user customized parameter values, verify the existence of generic prerequisites, etc.
Post-stage - Create a new database schema, modify a file or directory permissions on staged source files, etc.
Pre-activate - Upgrade an existing database schema, etc.
Post-activate - Remove a temporary banner ("Down for Maintenance"), reset a cache, etc.
Pre-rollback - Return configuration files or the database to their previous version, etc.
Post-rollback - Take the site out of maintenance mode, return the load balancer settings, etc.
Pre-deactivate - Put up a banner ("Down for Maintenance") for the previous version, etc.
Post-deactivate - Modify external configuration files, etc.
Pre-unstage - Back up specific applications files such as audit logs and other data files, etc.
Post-unstage - Clean up external files referencing the application (which are no longer needed), etc.

Deployment Hook Script Constants Examples

The following is a list of the available dynamic values that can be used by the deployment hook scripts:

ZS_APPLICATION_BASE_DIR - Contains the directory to which the application is deployed
ZS_CURRENT_APP_VERSION - In case an upgrade was performed, contains the version number of the current application
ZS_PHP_VERSION - Contains the PHP version that Zend Server uses
ZS_PREVIOUS_APP_VERSION - In case a rollback was performed, contains the previous version of the application
ZS_PREVIOUS_APPLICATION_BASE_DIR = In case a rollback was performed, contains the directory to which the application was deployed
ZS_RUN_ONCE_NODE - When deploying in a cluster, a single node ID is chosen to perform actions that only need to be done once. If the value of this constant is set to ‘1’ during deployment, the node is defined as the ‘run once node’
Important Note about Managed Deployment: When updating an application on a subset of the cluster, the run once mechanism is only applicable to the initial update. When you sync the other nodes with an additional update so all the nodes would have the same application version, the ZS_RUN_ONCE_NODE constant will always be 'false' on hook scripts, as the "run once" code cannot run again (usually a set-up code to align former application version to current, e.g. database scheme, resources etc.).
ZS_WEBSERVER_GID - Contains the web server user group ID (UNIX only)
ZS_WEBSERVER_TYPE - Contains a code representing the web server type (APACHE)
ZS_WEBSERVER_UID - Contains the web server user ID (UNIX only)
ZS_WEBSERVER_VERSION - Contains the web server version (2.2)
ZS_BASE_URL = Contains the base URL set for deployment

Usage Example

This example shows how to use the ZS_PREVIOUS_APP_VERSION value by a deployment hook script to upgrade previous application versions:

<?php
//... some code here ...//
if (getenv('ZS_RUN_ONCE_NODE') == true) {
	// this code section will run only ONCE on the entire cluster
}
if (getenv('ZS_PREVIOUS_APP_VERSION') !== false) {
	switch (getenv('ZS_PREVIOUS_APP_VERSION')) {
	case "1.4":
	//// perform upgrade from 1.4 -> 1.5
	case "1.5":
	//// perform upgrade from 1.5 -> 1.6
	case "1.6":
	//// perform upgrade from 1.6 -> CURRENT/1.7
	break;
	default:
	//// perform actions when current version is different than expected
	} // switch previous app versions actions
} // if there is a previous app version
else {
	//// perform actions specific to new installation, which cannot be performed with upgrade
} // complete new installation specific actions
//... more code here ...//
?>