Docs / Deployment


The deploy directory in an appserver.io distribution is the location where end users can place their deployment content (e.g. phar files) to have it deployed into the server runtime.

Users, particularly those running production systems, are encouraged to use the appserver.io application server (AS) management APIs to upload and deploy content.

Deployment Modes

The scanner only supports manual deployment mode, which means that you have to restart the server to process the deployment of your content. In this mode, the scanner will not attempt to directly monitor the deployment content and decide if or when the end user wishes the content to be deployed or undeployed. Instead, the scanner relies on a system of marker files, where the user’s addition or removal of a marker file serves as a sort of command telling the scanner to deploy, undeploy or redeploy content.

It is also possible to copy your unzipped content directly into the webapps folder. After restarting the appserver, your content will then be deployed without having any impact on the deployment scanner, because only zipped (.phar) content will be recognized.

Marker Files

The marker files always have the same name as the deployment content they relate to, but with an additional file suffix. For example, the marker file to indicate a deployment of the example.phar file, would be saved as example.phar.dodeploy. When appserver is started, the file suffix triggers the deployment.

Different marker file suffixes have different meanings. The relevant marker file types are:

Marker Description
.dodeploy Placed by the user to indicate that the given content should be deployed or redeployed into the runtime.
.deploying Placed by the deployment scanner service to indicate that it has noticed a .dodeploy file and is in the process of deploying the content. This marker file will be deleted when the deployment process completes.
.deployed Placed by the deployment scanner service to indicate that the given content has been deployed into the runtime. If an end user deletes this file and no other marker is available, the content will be undeployed.
.failed Placed by the deployment scanner service to indicate that the given content failed to deploy into the runtime. The content of the file will include some information about the cause of the failure. Note that removing this file will make the deployment eligible for deployment again.
.undeploying Placed by the deployment scanner service to indicate that it has noticed a .deployed file has been deleted and the content is being undeployed. This marker file will be deleted when the undeployment process completes.
.undeployed Placed by the deployment scanner service to indicate that the given content has been undeployed from the runtime. If an end content is being undeployed. This marker file will be deleted user deletes this file, it has no impact.

Basic workflows

All examples assume variable $AS points to the root of the appserver.io AS distribution.

Windows users: the examples below use UNIX shell commands; see the Windows Notes below.

  1. Add new zipped (.phar) content and deploy it:
$ cp target/example.phar $AS/deploy
$ touch $AS/deploy/example.phar.dodeploy
  1. Undeploy currently deployed zipped (.phar) content:
$ rm $AS/deploy/example.phar.deployed
  1. Replace currently deployed zipped (.phar) content with a new version and redeploy it:
$ cp target/example.phar $AS/deploy
$ mv $AS/deploy/example.phar.deployed $AS/deploy/example.phar.dodeploy

Windows Notes

The above examples use UNIX shell commands. Windows equivalents are the following.

UNIX Windows
cp src dest xcopy /y src dest
cp -r src dest xcopy /e /s /y src dest
rm afile del afile
touch afile echo » afile

Note that the behavior of touch and echo are different, but the differences are not relevant for the usage.