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

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