ZDT Deployment for PHP

Zero-Downtime Deployment for PHP

Zero-Downtime Deployment for PHP uses timestamped application directories and a symbolic link to switch incoming requests to a newly deployed version only after the update has completed. The previous version continues serving existing sessions during the transition.

In this article

How Zero-Downtime Deployment Works

Each deployment creates a separate timestamped application directory. A symbolic link named ROOT points to the application version currently handling new requests. After the updated files are fully deployed, the symbolic link switches to the new directory.

Separate versionsEach release is stored in a directory named with its creation date and time.
Atomic switchingThe ROOT symlink changes only after the new deployment is ready.
Existing sessionsThe previous application directory remains available for requests and sessions that began before the switch.
No server restartThe deployment is performed in soft mode without restarting the PHP application server.
i

Provider-dependent feature

The availability of Zero-Downtime Deployment depends on the hosting provider’s platform settings.

ZDT Deployment Workflow

1

Prepare a PHP environment

Create a new PHP environment or use an existing one. The documented example uses Apache PHP.

Create a PHP environment for zero-downtime deployment
Create or select the PHP environment that will host the application.
2

Enable zero-downtime deployment

Start application deployment and enable the Zero-Downtime Deployment option in the confirmation window.

For deployment through an archive or direct URL:

Enable zero-downtime deployment for an archive
Enable ZDT while deploying an archive or direct URL.

For deployment from a Git, SVN, or Bitbucket repository:

Enable zero-downtime deployment for a VCS project
Enable ZDT when adding or updating a VCS-based project.
!

ROOT context is required

The ZDT option is active only for deployment to the ROOT context of a PHP application server. Other contexts use the classic deployment method.

  • For VCS projects, the selected deployment mode is remembered for later automatic updates until changed manually.
  • Avoid hard-coded absolute application paths because the timestamped directory name changes after every deployment.
  • For the first archive or URL deployment over an existing application in the ROOT context, previous data is normally replaced by the new base installation.
3

Review the initial deployment

The first deployment creates a directory named in the ROOT_year.mm.dd-hh.mm.ss format and a ROOT symbolic link pointing to it.

First PHP application version deployed
The initial deployment creates the timestamped application folder and ROOT symlink.

Use SSH to inspect the symbolic link:

ls -l /var/www/webroot
PHP application ROOT symbolic link in SSH
The long file listing shows the ROOT symlink and its current target.
4

Deploy an updated version

A second timestamped directory is created while the current version remains active. After unpacking completes, the ROOT symlink switches to the new release.

Second PHP application version deployed
The current and updated application versions coexist during deployment.
!

User-generated content

With archive or URL deployment, move user-generated content manually from the previous directory to the new version. With VCS deployment, tracked and untracked content is copied automatically; use .gitignore to exclude unnecessary files.

5

Manage later releases

For each later atomic deployment, the oldest version is removed and the newest timestamped directory is added. Normally, only the current and previous versions remain.

Third PHP application deployment
The platform retains the latest and previous application versions.

To keep an older release from automatic removal, rename its folder before starting the next deployment.

Rename a PHP application version for backup
Rename a timestamped directory to preserve it as a backup version.

ZDT Implementation on PHP Servers

Apache PHP

Apache PHP uses the mod_realdoc module to manage symbolic-link switching. Its configuration is available under conf.d → mod_realdoc.conf.

Apache mod_realdoc zero-downtime configuration
Apache ZDT is controlled by the mod_realdoc configuration.

The RealpathEvery parameter defines how long the symbolic-link path is cached and how often it is refreshed. The documented platform value is 2. Restart the application-server node after changing it, and avoid setting it too high because that can delay symlink switching.

NGINX PHP

NGINX PHP provides atomic deployment through built-in configuration rather than an additional module. The relevant settings are located at the end of conf → nginx.conf.

NGINX PHP zero-downtime configuration
NGINX PHP includes built-in configuration for timestamped application directories.

Atomic and Classic Deployment Comparison

The source documentation compares both methods using a basic WordPress installation and Apache JMeter, with requests sent continuously before, during, and shortly after redeployment.

Classic Archive Deployment

Classic PHP deployment load-test graph
The classic deployment test shows a short period of failed requests during the update.

In the documented test, the classic method delivered an average response time of about 1.2 seconds but produced failed requests for approximately two seconds during deployment.

Zero-Downtime Deployment

Zero-downtime PHP deployment load-test graph
The ZDT test keeps successful request processing active throughout the update.

The ZDT test kept the response time generally stable, with a slight temporary increase while deployment and request handling ran together, and recorded no failed requests during the test.

Expected Result

PHP application updates are deployed to a new timestamped directory while the active version continues serving users. After the update succeeds, the ROOT symlink switches to the new version without restarting the application server.

Important Notes

  • ZDT works only for the ROOT deployment context.
  • Avoid hard-coded absolute application-directory paths.
  • Archive and URL deployments may require manual transfer of user-generated content.
  • VCS deployment copies tracked and untracked files; maintain an appropriate .gitignore.
  • The platform normally retains only the current and previous application versions.
  • Rename a version folder before the next deployment when it must be retained.
  • Changing Apache RealpathEvery requires a node restart.

Common Issues and Solutions

ZDT option is unavailableDeploy to the ROOT context and confirm that the hosting provider has enabled the feature.
User uploads disappear after archive deploymentMove user-generated files from the previous timestamped directory to the new release.
Application uses the wrong pathRemove hard-coded absolute release-directory paths and use paths that remain valid after symlink switching.
Symlink switch is delayedReview the Apache RealpathEvery value and avoid an unnecessarily high cache duration.
Required old version is deletedRename the timestamped directory before the next deployment so it is not selected for automatic cleanup.