Skip to content

Commit 41a5dca

Browse files
GitHubber17GitHubber17
authored
Merge pull request #83826 from JasonFreeberg/app-service-configure-java-refactor
Copied contents to Windows guide
2 parents 0e3aa32 + 3351ca4 commit 41a5dca

File tree

2 files changed

+263
-8
lines changed

2 files changed

+263
-8
lines changed

‎articles/app-service/configure-language-java.md

Lines changed: 261 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,269 @@ ms.custom: seodec18
1919

2020
# Configure a Windows Java app for Azure App Service
2121

22-
Azure App Service lets Java developers to quickly build, deploy, and scale their Tomcat or Java Standard Edition (SE) packaged web applications on a fully managed Windows-based service. Deploy applications with Maven plugins from the command line or in editors like IntelliJ, Eclipse, or Visual Studio Code.
22+
Azure App Service lets Java developers to quickly build, deploy, and scale their Tomcat web applications on a fully managed Windows-based service. Deploy applications with Maven plugins from the command line or in editors like IntelliJ, Eclipse, or Visual Studio Code.
2323

2424
This guide provides key concepts and instructions for Java developers using in App Service. If you've never used Azure App Service, you should read through the [Java quickstart](app-service-web-get-started-java.md) first. General questions about using App Service that aren't specific to the Java development are answered in the [App Service Windows FAQ](faq-configuration-and-management.md).
2525

26-
> [!NOTE]
27-
> Can't find what you're looking for? Please see the [Windows OSS FAQ](faq-configuration-and-management.md) or the [Java Linux configuration guide](containers/configure-language-java.md) for information on deploying and securing your Java app.
26+
## Deploying your app
27+
28+
You can use [Maven Plugin for Azure App Service](/java/api/overview/azure/maven/azure-webapp-maven-plugin/readme) to deploy your .war files. Deployment with popular IDEs is also supported with [Azure Toolkit for IntelliJ](/java/azure/intellij/azure-toolkit-for-intellij) or [Azure Toolkit for Eclipse](/java/azure/eclipse/azure-toolkit-for-eclipse).
29+
30+
Otherwise, your deployment method will depend on your archive type:
31+
32+
- To deploy .war files to Tomcat, use the `/api/wardeploy/` endpoint to POST your archive file. For more information on this API, please see [this documentation](https://docs.microsoft.com/azure/app-service/deploy-zip#deploy-war-file).
33+
34+
Do not deploy your .war using FTP. The FTP tool is designed to upload startup scripts, dependencies, or other runtime files. It is not the optimal choice for deploying web apps.
35+
36+
## Logging and debugging apps
37+
38+
Performance reports, traffic visualizations, and health checkups are available for each app through the Azure portal. For more information, see [Azure App Service diagnostics overview](overview-diagnostics.md).
39+
40+
### SSH console access
41+
42+
[!INCLUDE [Open SSH session in browser](../../includes/app-service-web-ssh-connect-builtin-no-h.md)]
43+
44+
### Stream diagnostic logs
45+
46+
[!INCLUDE [Access diagnostic logs](../../includes/app-service-web-logs-access-no-h.md)]
47+
48+
For more information, see [Streaming logs with the Azure CLI](troubleshoot-diagnostic-logs.md#streaming-with-azure-cli).
49+
50+
### App logging
51+
52+
Enable [application logging](troubleshoot-diagnostic-logs.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#enablediag) through the Azure portal or [Azure CLI](/cli/azure/webapp/log#az-webapp-log-config) to configure App Service to write your application's standard console output and standard console error streams to the local filesystem or Azure Blob Storage. Logging to the local App Service filesystem instance is disabled 12 hours after it is configured. If you need longer retention, configure the application to write output to a Blob storage container. Your Java and Tomcat app logs can be found in the */LogFiles/Application/* directory.
53+
54+
If your application uses [Logback](https://logback.qos.ch/) or [Log4j](https://logging.apache.org/log4j) for tracing, you can forward these traces for review into Azure Application Insights using the logging framework configuration instructions in [Explore Java trace logs in Application Insights](/azure/application-insights/app-insights-java-trace-logs).
55+
56+
57+
## Customization and tuning
58+
59+
Azure App Service supports out of the box tuning and customization through the Azure portal and CLI. Review the following articles for non-Java-specific web app configuration:
60+
61+
- [Configure app settings](configure-common.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#configure-app-settings)
62+
- [Set up a custom domain](app-service-web-tutorial-custom-domain.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json)
63+
- [Enable SSL](app-service-web-tutorial-custom-ssl.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json)
64+
- [Add a CDN](../cdn/cdn-add-to-web-app.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json)
65+
- [Configure the Kudu site](https://github.com/projectkudu/kudu/wiki/Configurable-settings)
66+
67+
### Set Java runtime options
68+
69+
To set allocated memory or other JVM runtime options, create an [app setting](configure-common.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json#configure-app-settings) named `JAVA_OPTS` with the options. App Service passes this setting as an environment variable to the Java runtime when it starts.
70+
71+
In the Azure portal, under **Application Settings** for the web app, create a new app setting named `JAVA_OPTS` that includes the additional settings, such as `-Xms512m -Xmx1204m`.
72+
73+
To configure the app setting from the Maven plugin, add setting/value tags in the Azure plugin section. The following example sets a specific minimum and maximum Java heap size:
74+
75+
```xml
76+
<appSettings>
77+
<property>
78+
<name>JAVA_OPTS</name>
79+
<value>-Xms512m -Xmx1204m</value>
80+
</property>
81+
</appSettings>
82+
```
83+
84+
Developers running a single application with one deployment slot in their App Service plan can use the following options:
85+
86+
- B1 and S1 instances: `-Xms1024m -Xmx1024m`
87+
- B2 and S2 instances: `-Xms3072m -Xmx3072m`
88+
- B3 and S3 instances: `-Xms6144m -Xmx6144m`
89+
90+
When tuning application heap settings, review your App Service plan details and take into account multiple applications and deployment slot needs to find the optimal allocation of memory.
91+
92+
### Turn on web sockets
93+
94+
Turn on support for web sockets in the Azure portal in the **Application settings** for the application. You'll need to restart the application for the setting to take effect.
95+
96+
Turn on web socket support using the Azure CLI with the following command:
97+
98+
```azurecli-interactive
99+
az webapp config set --name <app-name> --resource-group <resource-group-name> --web-sockets-enabled true
100+
```
101+
102+
Then restart your application:
103+
104+
```azurecli-interactive
105+
az webapp stop --name <app-name> --resource-group <resource-group-name>
106+
az webapp start --name <app-name> --resource-group <resource-group-name>
107+
```
108+
109+
### Set default character encoding
110+
111+
In the Azure portal, under **Application Settings** for the web app, create a new app setting named `JAVA_OPTS` with value `-Dfile.encoding=UTF-8`.
112+
113+
Alternatively, you can configure the app setting using the App Service Maven plugin. Add the setting name and value tags in the plugin configuration:
114+
115+
```xml
116+
<appSettings>
117+
<property>
118+
<name>JAVA_OPTS</name>
119+
<value>-Dfile.encoding=UTF-8</value>
120+
</property>
121+
</appSettings>
122+
```
123+
124+
### Pre-Compile JSP files
125+
126+
To improve performance of Tomcat applications, you can compile your JSP files before deploying to App Service. You can use the [Maven plugin](https://sling.apache.org/components/jspc-maven-plugin/plugin-info.html) provided by Apache Sling, or using this [Ant build file](https://tomcat.apache.org/tomcat-9.0-doc/jasper-howto.html#Web_Application_Compilation).
127+
128+
## Secure applications
129+
130+
Java applications running in App Service have the same set of [security best practices](/azure/security/security-paas-applications-using-app-services) as other applications.
131+
132+
### Authenticate users (Easy Auth)
133+
134+
Set up app authentication in the Azure portal with the **Authentication and Authorization** option. From there, you can enable authentication using Azure Active Directory or social logins like Facebook, Google, or GitHub. Azure portal configuration only works when configuring a single authentication provider. For more information, see [Configure your App Service app to use Azure Active Directory login](configure-authentication-provider-aad.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json) and the related articles for other identity providers. If you need to enable multiple sign-in providers, follow the instructions in the [customize App Service authentication](app-service-authentication-how-to.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json) article.
135+
136+
#### Tomcat and Wildfly
137+
138+
Your Tomcat or Wildfly application can access the user's claims directly from the servlet by casting the Principal object to a Map object. The Map object will map each claim type to a collection of the claims for that type. In the code below, `request` is an instance of `HttpServletRequest`.
139+
140+
```java
141+
Map<String, Collection<String>> map = (Map<String, Collection<String>>) request.getUserPrincipal();
142+
```
143+
144+
Now you can inspect the `Map` object for any specific claim. For example, the following code snippet iterates through all the claim types and prints the contents of each collection.
145+
146+
```java
147+
for (Object key : map.keySet()) {
148+
Object value = map.get(key);
149+
if (value != null && value instanceof Collection {
150+
Collection claims = (Collection) value;
151+
for (Object claim : claims) {
152+
System.out.println(claims);
153+
}
154+
}
155+
}
156+
```
157+
158+
To sign users out, use the `/.auth/ext/logout` path. To perform other actions, please see the documentation on [App Service Authentication and Authorization usage](https://docs.microsoft.com/azure/app-service/app-service-authentication-how-to). There is also official documentation on the Tomcat [HttpServletRequest interface](https://tomcat.apache.org/tomcat-5.5-doc/servletapi/javax/servlet/http/HttpServletRequest.html) and its methods. The following servlet methods are also hydrated based on your App Service configuration:
159+
160+
```java
161+
public boolean isSecure()
162+
public String getRemoteAddr()
163+
public String getRemoteHost()
164+
public String getScheme()
165+
public int getServerPort()
166+
```
167+
168+
To disable this feature, create an Application Setting named `WEBSITE_AUTH_SKIP_PRINCIPAL` with a value of `1`. To disable all servlet filters added by App Service, create a setting named `WEBSITE_SKIP_FILTERS` with a value of `1`.
169+
170+
### Configure TLS/SSL
171+
172+
Follow the instructions in the [Bind an existing custom SSL certificate](app-service-web-tutorial-custom-ssl.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json) to upload an existing SSL certificate and bind it to your application's domain name. By default your application will still allow HTTP connections-follow the specific steps in the tutorial to enforce SSL and TLS.
173+
174+
### Use KeyVault References
175+
176+
[Azure KeyVault](../key-vault/key-vault-overview.md) provides centralized secret management with access policies and audit history. You can store secrets (such as passwords or connection strings) in KeyVault and access these secrets in your application through environment variables.
177+
178+
First, follow the instructions for [granting your app access to Key Vault](app-service-key-vault-references.md#granting-your-app-access-to-key-vault) and [making a KeyVault reference to your secret in an Application Setting](app-service-key-vault-references.md#reference-syntax). You can validate that the reference resolves to the secret by printing the environment variable while remotely accessing the App Service terminal.
179+
180+
To inject these secrets in your Spring or Tomcat configuration file, use environment variable injection syntax (`${MY_ENV_VAR}`). For Spring configuration files, please see this documentation on [externalized configurations](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).
181+
182+
183+
## Configure APM platforms
184+
185+
This section shows how to connect Java applications deployed on Azure App Service on Linux with the NewRelic and AppDynamics application performance monitoring (APM) platforms.
186+
187+
### Configure New Relic
188+
189+
1. Create a New Relic account at [NewRelic.com](https://newrelic.com/signup)
190+
2. Download the Java agent from NewRelic, it will have a file name similar to *newrelic-java-x.x.x.zip*.
191+
3. Copy your license key, you'll need it to configure the agent later.
192+
4. Use the [Kudu console](https://github.com/projectkudu/kudu/wiki/Kudu-console) to create a new directory */home/site/wwwroot/apm*.
193+
5. Upload the unpacked New Relic Java agent files into a directory under */home/site/wwwroot/apm*. The files for your agent should be in */home/site/wwwroot/apm/newrelic*.
194+
6. Modify the YAML file at */home/site/wwwroot/apm/newrelic/newrelic.yml* and replace the placeholder license value with your own license key.
195+
7. In the Azure portal, browse to your application in App Service and create a new Application Setting.
196+
- If your app is using **Java SE**, create an environment variable named `JAVA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar`.
197+
- If you're using **Tomcat**, create an environment variable named `CATALINA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/newrelic/newrelic.jar`.
198+
199+
### Configure AppDynamics
200+
201+
1. Create an AppDynamics account at [AppDynamics.com](https://www.appdynamics.com/community/register/)
202+
2. Download the Java agent from the AppDynamics website, the file name will be similar to *AppServerAgent-x.x.x.xxxxx.zip*
203+
3. Use the [Kudu console](https://github.com/projectkudu/kudu/wiki/Kudu-console) to create a new directory */home/site/wwwroot/apm*.
204+
4. Upload the Java agent files into a directory under */home/site/wwwroot/apm*. The files for your agent should be in */home/site/wwwroot/apm/appdynamics*.
205+
5. In the Azure portal, browse to your application in App Service and create a new Application Setting.
206+
- If you're using **Java SE**, create an environment variable named `JAVA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name>` where `<app-name>` is your App Service name.
207+
- If you're using **Tomcat**, create an environment variable named `CATALINA_OPTS` with the value `-javaagent:/home/site/wwwroot/apm/appdynamics/javaagent.jar -Dappdynamics.agent.applicationName=<app-name>` where `<app-name>` is your App Service name.
208+
209+
> If you already have an environment variable for `JAVA_OPTS` or `CATALINA_OPTS`, append the `-javaagent:/...` option to the end of the current value.
210+
211+
## Data sources
212+
213+
### Tomcat
214+
215+
These instructions apply to all database connections. You will need to fill placeholders with your chosen database's driver class name and JAR file. Provided is a table with class names and driver downloads for common databases.
216+
217+
| Database | Driver Class Name | JDBC Driver |
218+
|------------|-----------------------------------------------|------------------------------------------------------------------------------------------|
219+
| PostgreSQL | `org.postgresql.Driver` | [Download](https://jdbc.postgresql.org/download.html) |
220+
| MySQL | `com.mysql.jdbc.Driver` | [Download](https://dev.mysql.com/downloads/connector/j/) (Select "Platform Independent") |
221+
| SQL Server | `com.microsoft.sqlserver.jdbc.SQLServerDriver` | [Download](https://docs.microsoft.com/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-2017#available-downloads-of-jdbc-driver-for-sql-server) |
222+
223+
To configure Tomcat to use Java Database Connectivity (JDBC) or the Java Persistence API (JPA), first customize the `CATALINA_OPTS` environment variable that is read in by Tomcat at start-up. Set these values through an app setting in the [App Service Maven plugin](https://github.com/Microsoft/azure-maven-plugins/blob/develop/azure-webapp-maven-plugin/README.md):
224+
225+
```xml
226+
<appSettings>
227+
<property>
228+
<name>CATALINA_OPTS</name>
229+
<value>"$CATALINA_OPTS -Ddbuser=${DBUSER} -Ddbpassword=${DBPASSWORD} -DconnURL=${CONNURL}"</value>
230+
</property>
231+
</appSettings>
232+
```
233+
234+
Or set the environment variables in the **Configuration** > **Application Settings** page in the Azure portal.
235+
236+
Next, determine if the data source should be available to one application or to all applications running on the Tomcat servlet.
237+
238+
#### Application-level data sources
239+
240+
1. Create a *context.xml* file in the *META-INF/* directory of your project. Create the *META-INF/* directory if it does not exist.
241+
242+
2. In *context.xml*, add a `Context` element to link the data source to a JNDI address. Replace the `driverClassName` placeholder with your driver's class name from the table above.
243+
244+
```xml
245+
<Context>
246+
<Resource
247+
name="jdbc/dbconnection"
248+
type="javax.sql.DataSource"
249+
url="${dbuser}"
250+
driverClassName="<insert your driver class name>"
251+
username="${dbpassword}"
252+
password="${connURL}"
253+
/>
254+
</Context>
255+
```
256+
257+
3. Update your application's *web.xml* to use the data source in your application.
258+
259+
```xml
260+
<resource-env-ref>
261+
<resource-env-ref-name>jdbc/dbconnection</resource-env-ref-name>
262+
<resource-env-ref-type>javax.sql.DataSource</resource-env-ref-type>
263+
</resource-env-ref>
264+
```
265+
266+
#### Finalize configuration
267+
268+
Finally, we will place the driver JARs in the Tomcat classpath and restart your App Service. Ensure that the JDBC driver files are available to the Tomcat classloader by placing them in the */home/tomcat/lib* directory. (Create this directory if it does not already exist.) To upload these files to your App Service instance, perform the following steps:
269+
270+
1. In the [Cloud Shell](https://shell.azure.com), install the webapp extension:
271+
272+
```azurecli-interactive
273+
az extension add -–name webapp
274+
```
275+
276+
2. Run the following CLI command to create an SSH tunnel from your local system to App Service:
277+
278+
```azurecli-interactive
279+
az webapp remote-connection create --resource-group <resource-group-name> --name <app-name> --port <port-on-local-machine>
280+
```
281+
282+
3. Connect to the local tunneling port with your SFTP client and upload the files to the */home/tomcat/lib* folder.
283+
284+
Alternatively, you can use an FTP client to upload the JDBC driver. Follow these [instructions for getting your FTP credentials](deploy-configure-credentials.md?toc=%2fazure%2fapp-service%2fcontainers%2ftoc.json).
28285

29286
## Configuring Tomcat
30287

@@ -43,7 +300,7 @@ Azure's supported Java Development Kit (JDK) is [Zulu](https://www.azul.com/down
43300

44301
Major version updates will be provided through new runtime options in Azure App Service for Windows. Customers update to these newer versions of Java by configuring their App Service deployment and are responsible for testing and ensuring the major update meets their needs.
45302

46-
Supported JDKs are automatically patched on a quarterly basis in January, April, July, and October of each year.
303+
Supported JDKs are automatically patched on a quarterly basis in January, April, July, and October of each year. For more information on Java on Azure, please see [this support document](https://docs.microsoft.com/azure/java/jdk/).
47304

48305
### Security updates
49306

0 commit comments

Comments
 (0)