Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Jetty Expanded Webapp Deploy"
(New page: {{Jetty Howto | introduction = You can make Jetty aware of your web application to be deployed in two ways: placing the web application in specific location or creating a deployment descr...) |
|||
| (5 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
{{Jetty Howto | {{Jetty Howto | ||
| − | | introduction = You can make Jetty aware of | + | | introduction = |
| + | |||
| + | {{Jetty Redirect|http://www.eclipse.org/jetty/documentation/current/configuring-deployment.html}} | ||
| + | |||
| + | You can make Jetty aware of web applications to be deployed in two ways: placing the web application in a specific location or creating a file that describes the deployment properties of your web application. In either case the web application may be either packed or unpacked WAR files. | ||
Before discussing the mechanisms for deploying Jetty applications it will be helpful to define two terms: | Before discussing the mechanisms for deploying Jetty applications it will be helpful to define two terms: | ||
| + | |||
'''Context''' is the name given to a deployed instance of a web application. If you're a programmer, a web application is to a context as a class is to an object of that class type. | '''Context''' is the name given to a deployed instance of a web application. If you're a programmer, a web application is to a context as a class is to an object of that class type. | ||
| − | '''Context Path''' is the URL path component that identifies the particular context. This is used by Jetty to route request to | + | |
| + | '''Context Path''' is the URL path component that identifies the particular context. This is used by Jetty to route request to the appropriate context. | ||
}} | }} | ||
| Line 11: | Line 17: | ||
Once the web application is detected it will be deployed in the following manner: | Once the web application is detected it will be deployed in the following manner: | ||
| − | |||
* If the web application is a file named foo.war it will be deployed as a context with a context path of /foo | * If the web application is a file named foo.war it will be deployed as a context with a context path of /foo | ||
* If the web application is a directory named foo/ will be deployed as a context with a context path of /foo. If the directory has a WEB-INF subdirectory, it will be treated as Servlet web application, otherwise it will be treated as a collection of static content. | * If the web application is a directory named foo/ will be deployed as a context with a context path of /foo. If the directory has a WEB-INF subdirectory, it will be treated as Servlet web application, otherwise it will be treated as a collection of static content. | ||
* If both a foo.war and a foo/ directory exists, then the one with the most recent last-modified date is used. | * If both a foo.war and a foo/ directory exists, then the one with the most recent last-modified date is used. | ||
| − | Note, if the web application file or directory is | + | Note, if the web application file or directory is named root.war or root, respectively, it will be deployed with the context path /. |
== Descriptor Based Deployment == | == Descriptor Based Deployment == | ||
| Line 22: | Line 27: | ||
=== Descriptor File Basics === | === Descriptor File Basics === | ||
| − | In a default Jetty installation, the $JETTY_HOME/contexts directory is scanned for context deployment descriptor files. So to deploy a web application using such a file simply place | + | In a default Jetty installation, the $JETTY_HOME/contexts directory is scanned for context deployment descriptor files. So to deploy a web application using such a file simply place the file in that directory. |
| − | The deployment descriptor file itself is a standard Jetty [[Jetty/Reference/jetty.xml syntax|configuration]] file that configures a | + | The deployment descriptor file itself is a standard Jetty [[Jetty/Reference/jetty.xml syntax|configuration]] file that configures a WebAppContext[http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/webapp/WebAppContext.html] class. For a basic installation you probably only need to set a couple properties: |
| − | * '''war''' - the path to the web application file/directory | + | * '''war''' - the filesystem path to the web application file/directory |
* '''contextPath''' - the context path to be used for the web application | * '''contextPath''' - the context path to be used for the web application | ||
| Line 41: | Line 46: | ||
</source> | </source> | ||
| − | Note, | + | Note, you can use the SystemProperty and Property elements in your descriptor file. As an example, if I set the system property myapp.home=/opt/myapp, I could rewrite the above example as: |
<source lang="xml"> | <source lang="xml"> | ||
| Line 49: | Line 54: | ||
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> | <Configure class="org.eclipse.jetty.webapp.WebAppContext"> | ||
<Set name="contextPath">/wiki</Set> | <Set name="contextPath">/wiki</Set> | ||
| − | <Set name="war"><SystemProperty name="myapp.home">/myapp.war</Set> | + | <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> |
</Configure> | </Configure> | ||
</source> | </source> | ||
| Line 56: | Line 61: | ||
=== Advanced Descriptor Files === | === Advanced Descriptor Files === | ||
| − | If you looked at the documentation for the | + | If you looked at the documentation for the WebAppContext[http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/webapp/WebAppContext.html] class, you'll have noticed that there are a lot more properties than just the two mentioned above. Here are some examples of doing more advanced things with your descriptor file. |
| − | <source lang="xml> | + | <source lang="xml"> |
<?xml version="1.0" encoding="ISO-8859-1"?> | <?xml version="1.0" encoding="ISO-8859-1"?> | ||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | ||
| Line 64: | Line 69: | ||
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> | <Configure class="org.eclipse.jetty.webapp.WebAppContext"> | ||
<Set name="contextPath">/wiki</Set> | <Set name="contextPath">/wiki</Set> | ||
| − | <Set name="war"><SystemProperty name="myapp.home">/myapp.war</Set> | + | <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> |
| − | <Get name=ServletContext> | + | <Set name="extractWAR">false</Set> |
| − | <Call name=setInitParameter> | + | </Configure> |
| + | </source> | ||
| + | In this example we tell Jetty not to expand the WAR file when deploying it. This can help make it clear that people should not be making changes to the temporary unpacked WAR as those changes will go away the next time the web application is deployed. | ||
| + | |||
| + | <source lang="xml"> | ||
| + | <?xml version="1.0" encoding="ISO-8859-1"?> | ||
| + | <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | ||
| + | |||
| + | <Configure class="org.eclipse.jetty.webapp.WebAppContext"> | ||
| + | <Set name="contextPath">/wiki</Set> | ||
| + | <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> | ||
| + | <Get name="ServletContext"> | ||
| + | <Call name="setInitParameter"> | ||
<Arg>myapp.config</Arg> | <Arg>myapp.config</Arg> | ||
<Arg><SystemProperty name="myapp.home">/config/app-config.xml</Arg> | <Arg><SystemProperty name="myapp.home">/config/app-config.xml</Arg> | ||
| Line 73: | Line 90: | ||
</Configure> | </Configure> | ||
</source> | </source> | ||
| − | In this example we retrieve the JavaEE Servlet context and set an initialization parameter on it. We could have also used the setAttribute method to set a Servlet context attribute. Note though | + | In this example we retrieve the JavaEE Servlet context and set an initialization parameter on it. We could have also used the setAttribute method to set a Servlet context attribute. Note though, since the web.xml for the web application is processed after the deployment descriptor the web.xml values will overwrite like-named parameters/attributes from the deployment descriptor. |
| − | <source lang="xml> | + | <source lang="xml"> |
<?xml version="1.0" encoding="ISO-8859-1"?> | <?xml version="1.0" encoding="ISO-8859-1"?> | ||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | ||
| Line 81: | Line 98: | ||
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> | <Configure class="org.eclipse.jetty.webapp.WebAppContext"> | ||
<Set name="contextPath">/wiki</Set> | <Set name="contextPath">/wiki</Set> | ||
| − | <Set name="war"><SystemProperty name="myapp.home">/myapp.war</Set> | + | <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> |
<Set name="overrideDescriptor">/opt/myapp/overlay-web.xml</Set> | <Set name="overrideDescriptor">/opt/myapp/overlay-web.xml</Set> | ||
</Configure> | </Configure> | ||
</source> | </source> | ||
| − | In this example we set a special web.xml override descriptor. | + | In this example we set a special web.xml override descriptor. This descriptor is processed after the web application's web.xml and so may override like-named parameters/attributes. This can be quite useful if you want to add parameters or additional Servlet mappings without breaking open a packed WAR file. |
| − | <source lang="xml> | + | <source lang="xml"> |
<?xml version="1.0" encoding="ISO-8859-1"?> | <?xml version="1.0" encoding="ISO-8859-1"?> | ||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> | ||
| Line 93: | Line 110: | ||
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> | <Configure class="org.eclipse.jetty.webapp.WebAppContext"> | ||
<Set name="contextPath">/wiki</Set> | <Set name="contextPath">/wiki</Set> | ||
| − | <Set name="war"><SystemProperty name="myapp.home">/myapp.war | + | <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> |
| − | + | ||
</Configure> | </Configure> | ||
| + | |||
| + | <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"> | ||
| + | <Arg></Arg> | ||
| + | <Arg>jdbc/DSTest</Arg> | ||
| + | <Arg> | ||
| + | <New class="org.apache.commons.dbcp.BasicDataSource"> | ||
| + | <Set name="driverClassName">org.some.Driver</Set> | ||
| + | <Set name="url">jdbc.url</Set> | ||
| + | <Set name="username">jdbc.user</Set> | ||
| + | <Set name="password">jdbc.pass</Set> | ||
| + | </New> | ||
| + | </Arg> | ||
| + | </New> | ||
</source> | </source> | ||
| − | In this example we | + | |
| + | In this example we configure not only the web application context but also a database connection pool (see [[Jetty/Howto/Configure_JNDI_Datasource|Configure JNDI Datasource]]) which our application would use. If the web.xml did not include a reference to this data source the override descriptor mechanism, shown in the previous example, could be used to include it. | ||
== Deploying with the Jetty Maven Plugin == | == Deploying with the Jetty Maven Plugin == | ||
Latest revision as of 15:10, 23 April 2013
Contents
Introduction
THIS IS NOT THE DOCUMENTATION YOU ARE LOOKING FOR!!!!!
All development and stable releases are being performed with Jetty 9 and Jetty 10.
This wiki is now officially out of date and all content has been moved to the Jetty Documentation Hub
You can make Jetty aware of web applications to be deployed in two ways: placing the web application in a specific location or creating a file that describes the deployment properties of your web application. In either case the web application may be either packed or unpacked WAR files.
Before discussing the mechanisms for deploying Jetty applications it will be helpful to define two terms:
Context is the name given to a deployed instance of a web application. If you're a programmer, a web application is to a context as a class is to an object of that class type.
Context Path is the URL path component that identifies the particular context. This is used by Jetty to route request to the appropriate context.
Location Based Deployment
In a default Jetty installation, the directory $JETTY_HOME/webapps is scanned at startup for web applications to be deployed. So to deploy your web application simply place it in that directory.
Once the web application is detected it will be deployed in the following manner:
- If the web application is a file named foo.war it will be deployed as a context with a context path of /foo
- If the web application is a directory named foo/ will be deployed as a context with a context path of /foo. If the directory has a WEB-INF subdirectory, it will be treated as Servlet web application, otherwise it will be treated as a collection of static content.
- If both a foo.war and a foo/ directory exists, then the one with the most recent last-modified date is used.
Note, if the web application file or directory is named root.war or root, respectively, it will be deployed with the context path /.
Descriptor Based Deployment
Using the location based deployment model is quick and easy but, sometimes, you may need to tune certain deployment properties (e.g., you want to deploy with a context path that is not based on the file name or you want to define a special database connection pool just for this web application). To do this you can use a context deployment descriptor file.
Descriptor File Basics
In a default Jetty installation, the $JETTY_HOME/contexts directory is scanned for context deployment descriptor files. So to deploy a web application using such a file simply place the file in that directory.
The deployment descriptor file itself is a standard Jetty configuration file that configures a WebAppContext[1] class. For a basic installation you probably only need to set a couple properties:
- war - the filesystem path to the web application file/directory
- contextPath - the context path to be used for the web application
As an example, here is a descriptor file that deploys the file /opt/myapp/myapp.war to the context path /wiki.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war">/opt/myapp/myapp.war</Set> </Configure>
Note, you can use the SystemProperty and Property elements in your descriptor file. As an example, if I set the system property myapp.home=/opt/myapp, I could rewrite the above example as:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> </Configure>
Now, if I need to change the home path for my application I can simply change the system property. This can be quite useful if you are a developer and frequently switching between multiple version of an app.
Advanced Descriptor Files
If you looked at the documentation for the WebAppContext[2] class, you'll have noticed that there are a lot more properties than just the two mentioned above. Here are some examples of doing more advanced things with your descriptor file.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> <Set name="extractWAR">false</Set> </Configure>
In this example we tell Jetty not to expand the WAR file when deploying it. This can help make it clear that people should not be making changes to the temporary unpacked WAR as those changes will go away the next time the web application is deployed.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> <Get name="ServletContext"> <Call name="setInitParameter"> <Arg>myapp.config</Arg> <Arg><SystemProperty name="myapp.home">/config/app-config.xml</Arg> </Call> </Get> </Configure>
In this example we retrieve the JavaEE Servlet context and set an initialization parameter on it. We could have also used the setAttribute method to set a Servlet context attribute. Note though, since the web.xml for the web application is processed after the deployment descriptor the web.xml values will overwrite like-named parameters/attributes from the deployment descriptor.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> <Set name="overrideDescriptor">/opt/myapp/overlay-web.xml</Set> </Configure>
In this example we set a special web.xml override descriptor. This descriptor is processed after the web application's web.xml and so may override like-named parameters/attributes. This can be quite useful if you want to add parameters or additional Servlet mappings without breaking open a packed WAR file.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> </Configure> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"> <Arg></Arg> <Arg>jdbc/DSTest</Arg> <Arg> <New class="org.apache.commons.dbcp.BasicDataSource"> <Set name="driverClassName">org.some.Driver</Set> <Set name="url">jdbc.url</Set> <Set name="username">jdbc.user</Set> <Set name="password">jdbc.pass</Set> </New> </Arg> </New>
In this example we configure not only the web application context but also a database connection pool (see Configure JNDI Datasource) which our application would use. If the web.xml did not include a reference to this data source the override descriptor mechanism, shown in the previous example, could be used to include it.
Deploying with the Jetty Maven Plugin
If you develop your web application as a maven project, then it can be deployed in jetty with "mvn jetty:run" using the Jetty Maven Plugin
Maven lets you build your web applications by overlaying on other template web applications (eg Cometd) and will manage the transitive dependencies needed to populate WEB-INF/lib
OSGi web application bundle
TBD
Embedded Usage
Web applications can also be deployed into embedded jetty, either via direct configuration or via configuration of a deployer. For an example see the Embedding Jetty Tutorial