JBoss.orgCommunity Documentation

Chapter 4. TorqueBox Application Deployment

4.1. Rake tasks
4.2. The torquebox command
4.3. Manual deployment
4.3.1. Deployment markers
4.3.2. Manually deploying with a descriptor
4.3.3. Manually deploying an archive
4.4. Zero Downtime Redeployment

The TorqueBox Application Server is capable of serving many applications simultaneously. To add your application to the server, you must deploy it. To deploy an application, you tell TorqueBox where to find it. You can do so via our rake tasks, the torquebox command, or manually.

TorqueBox provides a gem that includes Rake tasks which assist in the deployment to and undeployment from an instance of the TorqueBox Server in addition to other server management tasks. Please see Chapter 18, TorqueBox Rake Support for details.

In addition to the rake tasks, TorqueBox provides an executable script that assists in the deployment to and undeployment from an instance of the TorqueBox Server in addition to other server management tasks. Please see Chapter 17, The torquebox Command for details.

To customize some of the aspects of deployment, instead of using the Rake tasks or the torquebox command, you may manually deploy your artifacts. This manual process is identical to the automation that the tasks and command provide.

To deploy manually, you'll need to create two files in the deployment directory, which is by default $JBOSS_HOME/standalone/deployments/. The first file is either a small text file (called a deployment descriptor) or a TorqueBox archive, depending on whether you are deploying an application from where it sits on disk or as a self-contained archive. The second file you will need to create is a deployment marker. TorqueBox uses various deployment markers to manage the lifecycle of a deployment.

AS7 (and therefore TorqueBox) uses a set of files in the deployment directory called deployment markers to manage the deployment lifecycle of a deployment artifact. A deployment marker for a deployment artifact is an empty file with the same name as the artifact with the marker suffix appended. For manual deployment, you usually only need to be concerned with two of them: .dodeploy and .deployed. There are quite a few other marker files, and you see the full list in the AS7 docs.

  • .dodeploy - signifies that the artifact should be deployed. You would create this file to trigger deployment. TorqueBox removes this marker file after completing the deployment.
  • .deployed - signifies that the artifact has been deployed. TorqueBox creates this file after completing the deployment.

To trigger redeployment of an already deployed application, simply update the timestamp on its .deployed marker file. To undeploy an application, remove the .deployed marker file. Example:

# redeploy
$ touch $JBOSS_HOME/standalone/deployments/my-app-knob.yml.deployed
# undeploy
$ rm $JBOSS_HOME/standalone/deployments/my-app-knob.yml.deployed

Applications may be deployed from where they sit on disk. To do so manually, you need to write a deployment descriptor that references the application directory from its root entry to $JBOSS_HOME/standalone/deployments/. The descriptor is a YAML file with a required suffix of -knob.yml. For details on the various options for authoring deployment descriptors, see Chapter 5, TorqueBox Deployment Descriptors. For TorqueBox to notice your deployment, you'll also need to create an empty .dodeploy marker. Example:

$ echo "application:\n  root: /path/to/my-app/" > $JBOSS_HOME/standalone/deployments/my-app-knob.yml
$ touch $JBOSS_HOME/standalone/deployments/my-app-knob.yml.dodeploy

TorqueBox now supports redeploying part or all of an application without any downtime. For now, this only works with regular exploded deployments (not archives). To initiate a zero downtime deployment, copy the updated application code to the server (overwriting the currently running files) and touch $APP_ROOT/tmp/restart.txt, where $APP_ROOT is the root directory of your application. Please be aware that Torquebox will need permissions to read and delete from the $APP_ROOT/tmp directory as the restart.txt file will get deleted once Torquebox detects one of the redeployment markers. The application's web runtime will restart, sending all new web requests to the updated runtime while existing requests finish in the old runtimes. Other runtimes may be restarted by touching the appropriate redeployment markers, listed below.

If you don't want to use fileystem markers, runtime pools can also be restarted by JMX operations. Expand the MBean tree under torquebox.pools -> <app_name> to see all the runtime pools for each application. Each pool has a restart operation that behaves identically as touching that pool's restart marker.

TorqueBox Services and Runtime Restarts

Note that when the services runtime gets restarted any running services will be stopped and new service instances initialized and started.