[jbossweb-commits] JBossWeb SVN: r1780 - trunk/webapps/docs.

Author: jfrederic.clere(a)jboss.com Date: 2011-07-13 11:43:16 -0400 (Wed, 13 Jul 2011) New Revision: 1780 Modified: trunk/webapps/docs/deployer-howto.xml Log: Arrange deployer part. Modified: trunk/webapps/docs/deployer-howto.xml =================================================================== --- trunk/webapps/docs/deployer-howto.xml 2011-07-12 10:25:24 UTC (rev 1779) +++ trunk/webapps/docs/deployer-howto.xml 2011-07-13 15:43:16 UTC (rev 1780) @@ -8,6 +8,7 @@ <properties> <author>Allistair Crossley</author> + <author>Jean-Frederic Clere</author> <title>JBoss Web Web Application Deployment</title> </properties> @@ -39,53 +40,21 @@ <ul> <li>Statically; the web application is setup before JBoss Web is started</li> <li> - Dynamically; in conjunction with the JBoss Web Manager web application or - manipulating already deployed web applications + Dynamically; Using the command line or the Web Management Interface of AS7 + or manipulating already deployed web applications </li> </ul> </p> - <p> - The JBoss Web Manager is a tool that allows URL-based web application - deployment features. There is also a tool called the Client Deployer, - which is a command shell based script that interacts with the JBoss Web - Manager but provides additional functionality such as compiling and - validating web applications as well as packaging web application into - web application resource (WAR) files. - </p> </section> <section name="Installation"> <p> - There is no installation required for static deployment of web + There is no installation required for static or dynamic deployment of web applications as this is provided out of the box by JBoss Web. Nor is any installation required for deployment functions with the JBoss Web Manager, although some configuration is required as detailed in the - JBoss Web Manager manual. An installation is however required if you wish - to use the JBoss Web Client Deployer (TCD). + JBoss Web Manager manual. </p> - <p> - The TCD is not packaged with the JBoss Web core - distribution, and must therefore be downloaded separately from - the Downloads area. The download is usually labelled - <i>jbossweb-2.1.x-deployer</i>. - </p> - <p> - TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation. - Your environment should define an ANT_HOME environment value pointing to - the root of your Ant installation, and a JAVA_HOME value pointing to - your Java installation. Additionally, you should ensure Ant's ant - command, and the Java javac compiler command run from the command shell - that your operating system provides. - </p> - <ol> - <li>Download the TCD distribution</li> - <li> - The TCD package need not be extracted into any existing JBoss Web - installation, it can be extracted to any location. - </li> - <li>Read Using the <a href="#Deploying using the Client Deployer Package"> - JBoss Web Client Deployer</a></li> - </ol> </section> <section name="A word on Contexts"> @@ -98,26 +67,8 @@ In order to configure a Context within JBoss Web a <i>Context Descriptor</i> is required. A Context Descriptor is simply an XML file that contains JBoss Web related configuration for a Context, e.g naming resources or - session manager configuration. In earlier versions of - JBoss Web the content of a Context Descriptor configuration was often stored within - JBoss Web's primary configuration file <i>server.xml</i> but this is now - discouraged (although it currently still works). + session manager configuration. </p> - <p> - Context Descriptors not only help JBoss Web to know how to configure - Contexts but other tools such as the JBoss Web Manager and TDC often use - these Context Descriptors to perform their roles properly. - </p> - <p> - The locations for Context Descriptors are; - <ol> - <li>$CATALINA_HOME/conf/[enginename]/[hostname]/context.xml</li> - <li>$CATALINA_HOME/webapps/[webappname]/META-INF/context.xml</li> - </ol> - Files in (1) are named [webappname].xml but files in (2) are named - context.xml. If a Context Descriptor is not provided for a Context, - JBoss Web configures the Context using default values. - </p> </section> <section name="Deployment on JBoss Web startup"> @@ -131,30 +82,10 @@ location, or a compressed web application resource .WAR file. </p> <p> - The web applications present in the location specified by the Host's - (default Host is "localhost") <code>appBase</code> attribute (default - appBase is "$CATALINA_HOME/webapps") will be deployed on JBoss Web startup - only if the Host's <code>deployOnStartup</code> attribute is "true". + The web applications present in the location + ${jboss.server.base.dir}/standalone/deployments/ + will be deployed on JBoss Web startup. </p> - <p> - The following deployment sequence will occur on JBoss Web startup in that - case: - </p> - <ol> - <li>Any Context Descriptors will be deployed first.</li> - <li> - Exploded web applications not referenced by any Context - Descriptor will then be deployed. If they have an associated - .WAR file in the appBase and it is newer than the exploded web application, - the exploded directory will be removed and the webapp will be - redeployed from the .WAR - </li> - <li>.WAR files will be deployed</li> - </ol> - <p> - Note again that for each deployed web application, a - Context Descriptor will be created <i>unless one exists already</i>. - </p> </section> <section name="Deploying on a running JBoss Web server"> @@ -162,167 +93,73 @@ It is possible to deploy web applications to a running JBoss Web server. </p> <p> - If the Host <code>autoDeploy</code> attribute is "true", the Host will - attempt to deploy and update web applications dynamically, as needed, - for example if a new .WAR is dropped into the <code>appBase</code>. - For this to work, the Host needs to have background processing - enabled which is the default configuration. + Depending on the <code>deployment-scanner</code> configuration + the application web are deployed dynamicly and/or + updated, the <code>deployment-scanner</code> is a sub system: +<source> +[standalone@localhost:9999 /] ./subsystem=deployment-scanner:read-resource(recursive=true) +{ + "outcome" => "success", + "result" => {"scanner" => {"default" => { + "auto-deploy-exploded" => true, + "auto-deploy-zipped" => true, + "deployment-timeout" => 60L, + "name" => "default", + "path" => "deployments", + "relative-to" => "jboss.server.base.dir", + "scan-enabled" => true, + "scan-interval" => 5000 + }}} +} +</source> + </p><p> + For example if a new .WAR is dropped into the <code>${jboss.server.base.dir}/standalone/deployments/</code> + directory it will be deployed automaticly. </p> - - <p> - <code>autoDeploy</code> set to "true" and a running JBoss Web allows for: - </p> + + <p>The webapps are deployed or redeployed in the following cases:</p> <ul> - <li>Deployment of .WAR files copied into the Host <code>appBase</code>.</li> + <li>Deployment of .WAR files copied into the <code>${jboss.server.base.dir}/standalone/deployments/</code> directory. + </li> <li> - Deployment of exploded web applications which are - copied into the Host <code>appBase</code>. + Deployment of exploded web applications which that are copied there too. </li> <li> Re-deployment of a web application which has already been deployed from - a .WAR when the new .WAR is provided. In this case the exploded - web application is removed, and the .WAR is expanded again. - Note that the explosion will not occur if the Host is configured - so that .WARs are not exploded with a <code>unpackWARs</code> - attribute set to "false", in which case the web application - will be simply redeployed as a compressed archive. + a .WAR when the new .WAR is provided. </li> <li> Re-deployment of a web application if the /WEB-INF/web.xml file (or any other resource defined as a WatchedResource) is updated. </li> <li> - Re-deployment of a web application if the Context Descriptor file from which - the web application has been deployed is updated. + Undeployment of a web application if the .WAR file is removed of the + exploded files are removed. </li> - <li> - Re-deployment of a web application if a Context Descriptor file (with a - filename corresponding to the Context path of the previously deployed - web application) is added to the - <code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code> - directory. - </li> - <li> - Undeployment of a web application if its document base (docBase) - is deleted. Note that on Windows, this assumes that anti-locking - features (see Context configuration) are enabled, otherwise it is not - possible to delete the resources of a running web application. - </li> </ul> - <p> - Note that web application reloading can also be configured in the loader, in which - case loaded classes will be tracked for changes. - </p> </section> - <section name="Deploying using the JBoss Web Manager"> + <section name="Deploying using the command line"> <p> - The JBoss Web Manager is covered in its <a href="manager-howto.html">own manual page</a>. + Use the command line: + <code>${jboss.server.base.dir}/bin/jboss-admin.sh</code> + For example: + <source> + bin/jboss-admin.sh + You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands. + [disconnected /] connect + Connected to standalone controller at localhost:9999 + [standalone@localhost:9999 /] deploy /home/jfclere/jbossweb_sandbox/webapps/myapp.war + 'myapp.war' deployed successfully. + </source> + To undeploy: + <source> + [standalone@localhost:9999 /] undeploy myapp.war + Successfully undeployed myapp.war. + </source> </p> </section> - <section name="Deploying using the Client Deployer Package"> - <p> - Finally, deployment of web application may be achieved using the - JBoss Web Client Deployer. This is a package which can be used to - validate, compile, compress to .WAR, and deploy web applications to - production or development JBoss Web servers. It should be noted that this feature - uses the JBoss Web Manager and as such the target JBoss Web server should be - running. - </p> - - <p> - It is assumed the user will be familar with Apache Ant for using the TCD. - Apache Ant is a scripted build tool. The TCD comes pre-packaged with a - build script to use. Only a modest understanding of Apache Ant is - required (installation as listed earlier in this page, and familiarity - with using the operating system command shell and configuring - environment variables). - </p> - - <p> - The TCD includes Ant tasks, the Jasper page compiler for JSP compilation - before deployment, as well as a task which - validates the web application Context Descriptor. The validator task (class - <code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter: - the base path of an exploded web application. - </p> - - <p> - The TCD uses an exploded web application as input (see the list of the - properties used below). A web application that is programatically - deployed with the deployer may include a Context Desciptor in - <code>/META-INF/context.xml</code>. - </p> - - <p> - The TCD includes a ready-to-use Ant script, with the following targets: - </p> - <ul> - <li> - <code>compile</code> (default): Compile and validate the web - application. This can be used standalone, and does not need a running - JBoss Web server. The compiled application will only run on the associated - JBoss Web server release, and is not guaranteed to work on another - JBoss Web release, as the code generated by Jasper depends on its runtime - component. It should also be noted that this target will also compile - automatically any Java source file located in the - <code>/WEB-INF/classes</code> folder of the web application.</li> - <li> - <code>deploy</code>: Deploy a web application (compiled or not) to - a JBoss Web server. - </li> - <li><code>undeploy</code>: Undeploy a web application</li> - <li><code>start</code>: Start web application</li> - <li><code>reload</code>: Reload web application</li> - <li><code>stop</code>: Stop web application</li> - </ul> - - <p> - In order for the deployment to be configured, create a file - called <code>deployer.properties</code> in the TCD installation - directory root. In this file, add the following name=value pairs per - line: - </p> - - <p> - Additionally, you will need to ensure that a user has been - setup for the target JBoss Web Manager (which TCD uses) otherwise the TCD - will not authenticate with the JBoss Web Manager and the deployment will - fail. To do this, see the JBoss Web Manager page. - </p> - - <ul> - <li> - <code>build</code>: The build folder used will be, by default, - <code>${build}/webapp/${path}</code>. After the end of the execution - of the <code>compile</code> target, the web application .WAR will be - located at <code>${build}/webapp/${path}.war</code>. - </li> - <li> - <code>webapp</code>: The directory containing the exploded web application - which will be compiled and validated. By default, the folder is - <code>myapp</code>. - </li> - <li> - <code>path</code>: Deployed context path of the web application, - by default <code>/myapp</code>. - </li> - <li> - <code>url</code>: Absolute URL to the JBoss Web Manager web application of a - running JBoss Web server, which will be used to deploy and undeploy the - web application. By default, the deployer will attempt to access - a JBoss Web instance running on localhost, at - <code>http://localhost:8080/manager</code>. - </li> - <li> - <code>username</code>: JBoss Web Manager username (user should have a role of - manager) - </li> - <li><code>password</code>: JBoss Web Manager password.</li> - </ul> - </section> - </body> </document>