Deployment Settings
The Application Deployment Settings page allows you to configure behavior and policies related to application deployment on your Zend Server infrastructure.
The Deployment Settings page:
A "hot" application update, or upgrade, means that you can actively replace application resources while the application is kept running. It is very appealing to use and therefore, Zend Server has this new option as the default deployment mode, starting from version 9.1.
A "cold" application update, or upgrade, means that you will go through a web server restart once your new application files are deployed. This is the "Classic" mode, which guarantees flush of temporary resources when serving new application files with fresh web server processes.
Technical differences
To understand better how "hot" update works, and be able to decide which update mode is better for your applications deployment flow, we need to re-visit the classic "cold" update flow.
Zend Server deploys and upgrades applications as a complete set of files, including all resources, rules and update scripts, in a fresh new application directory on the server filesystem. This is dictated by a continuous delivery paradigm which guarantees more control over application versions, fallback when needed, and proper validation facility to prevent live applications from breaking due to upgrade actions.
Once the application directory is fully populated with the application files, Zend Server switch the host configuration to a new document root and restarts the web server in order to load configuration files and serve the new app version. The former application version directory is still available on the server filesystem, in case things go wrong with the new version and a "fallback" action will be taken by the admin to revert the application and fix the issues which broke the new version, then fix and re-deploy to upgrade.
What happens when using "hot" update mode?
Zend Server hot deployment feature will be doing everything as with "cold" deployment, except for 2 things.
- On the filesystem, a symlink (symbolic link) will be created under the application path, pointing to the application directory new version being deployed. The symlink will then be used to configure the web server host configuration file, instead of using the application directory by itself.
- The web server will not be restarted, if the symlink pointing to the application version directory is already placed on the filesystem. Instead of updating the web server host configuration with a new application version directory, Zend Server hot update will only update the symlink on the filesystem, which does not require configuration change, nor restart of the web server.
Lets see a working example.
Example flow in Cold (classic) update mode
Current application version 2.0.0 Directory: /usr/local/zend/var/apps/http/mydomain/80/2.0.0_7
Web server host configuration has DocumentRoot: /usr/local/zend/var/apps/http/mydomain/80/2.0.0_7
New application version 3.0.0 deployed: /usr/local/zend/var/apps/http/mydomain/80/3.0.0_9
Web server host configuration is updated with new DocumentRoot: /usr/local/zend/var/apps/http/mydomain/80/3.0.0_9
Web server restart is done after successful deployment, loading the new host configuration, serving new application version 3.0.0.
Example flow in Hot update mode
Application version 2.0.0 was already deployed in hot update mode, and web server restarted once. Hot update mode is enabled before and during this step.
The filesystem looks a bit different now, including a new symlink called "active" under the application path, and pointing to the application "real" DocumentRoot.
/usr/local/zend/var/apps/http/mydomain/80/2.0.0_7/
/usr/local/zend/var/apps/http/mydomain/80/active -> /usr/local/zend/var/apps/http/mydomain/80/2.0.0_7/
Web server host configuration use the symlink as DocumentRoot: /usr/local/zend/var/apps/http/mydomain/80/active
New application version 3.0.0 is now "hot" deployed: /usr/local/zend/var/apps/http/mydomain/80/3.0.0_9
The "active" symlink is recreated on the filesystem, pointing to new application version path:
/usr/local/zend/var/apps/http/mydomain/80/active -> /usr/local/zend/var/apps/http/mydomain/80/3.0.0_9
At this point, there is no need to restart the web server, as nothing changed in the host configuration, and it can serve the new application files right away by following the filesystem "active" symlink.
Hot Update "enforcements"
As "hot" update is not a new concept, and using symlinks is a common practice on production servers, Zend Server helps to insure the new application version starts off with as less leftovers as possible by clearing PHP opcode caches and realpath entries when serving new version application files.
With any application including other PHP files during the request, you can use an application aware API call zend_deployment_application_path() to get application path and base your includes on the return value. However, this can backfire in hot update situation, where a single request can run through 2 (or even more) versions of the application (if taking long enough). See the next section to understand more on using the API in your application code, considering a hot update can be in effect anytime.
Using zend_deployment_application_path() API call within your PHP code
Hot update mechanism can often create the following situation:
1. Application version A request runs, including some file from version A
2. Hot update is made during the request, and Application version B is starting to get requests
3. Normally, requests still serving version A will have no effect on included files and get the version throughout the request
When you set the request include path, which is often portable (not depending on php.ini include_path), you rely on absolute or relative path to the calling file / bootstrap, using PHP magic constants such as __DIR__ or dirname(__FILE__) to determine runtime path.
Since the physical location of the calling script does not change by hot update during the live request, it is safe to keep calling included files while a hot update is taking place, and still get the matching version copies.
Let's explain what you should NOT be doing then.
Using an API call to fetch the current application path at runtime, will produce different output BEFORE and AFTER a hot update.
Application version A index.php:
<?php
echo zend_deployment_application_path();
// result: /usr/local/zend/var/apps/http/__default__/0/hot/2.0.0_3
echo __DIR__;
// result: /usr/local/zend/var/apps/http/__default__/0/hot/2.0.0_3
Now, once version B deploys completely,
and application version A request is still running (with hot update, no web server restart made)
<?php
echo zend_deployment_application_path();
// result: /usr/local/zend/var/apps/http/__default__/0/hot/3.0.0_4
echo __DIR__;
// result: /usr/local/zend/var/apps/http/__default__/0/hot/2.0.0_3
So, as you can see - if you fetch the application path in the beginning of the request, and again after a hot update is made, you CAN get the wrong version.
Conclusion - if you are using the API call to fetch the current application path at runtime, make sure you store it and use the stored value throughout the request, for including application code from the correct application version.
Example Code (proper handling of application path during Hot update mode):
<?php
$my_include_path = zend_deployment_application_path();
include $my_include_path."/includes/helper_code1.inc.php";
// Some code here
// or using include or require again in an included file
include $my_include_path."/includes/helper_code2.inc.php";
Choosing update mode for application upgrades
Please consider the following arguments to properly choose which deployment update mode to dictate on your Zend Server installation.
Zend Server for Development - use "hot" or "cold" deployment updates according to your production settings, in order to "catch" improper deployments and find out the failures before you perform the same updates in staging and production. To speed up deployments of large applications while being developed, and as your overall "preferred" update mode - use "hot" update (also the default for new Zend Server installations).
Zend Server for Testing (Staging) - use the same deployment update mode you use in production, as it should mirror and test the same flows and continuous delivery patterns.
Zend Server for Production - If your application update hold many changes on include files, classes and methods, and there is a big chance (or actual evidence) of running into problems while busy server(s) have 2 application versions being served for a short period of time - switch and stay in "cold" update mode until you complete your update cycle and web server restart policy (see notes below).
For any other update scenarios, considering Zend Server have "enforcements" or immunities for hot update mode which prevents many known issues with "symlink updates" - keep the default of "hot" update mode or switch to it in the Deployment Settings page.
- When a new application is deployed, a web server restart will be made regardless of the application update mode, in order to update the host configuration with a document root symlink, and serve the new application files.
- When you use "hot" update to upgrade an application which was earlier updated in "cold" update mode, the symlink has to be place on the filesystem and be updated in the host configuration file. This flow also requires web server restart in order to reload configuration files and serve the new application version files. From the next "hot" update onwards, the symlink will be updated instead of the web server configuration, and a web server restart will not be required when "hot' updating the application.
- If you have just upgraded from earlier Zend Server 9.0, you have been using "cold" update mode so far, therefore, the hot update settings will carry on the same way until you manually switch your deployment to "hot" update mode, if desirable.
- As a reminder - In a clustered environment, web server restart strategy applies to "cold" update mode as before, but also to "hot" updates which needs to update a symlink first, i.e. - when switching from "cold" update mode.