cli and data source steps

cephalin · cephalin · commit 678d954379be · 2024-10-31T17:04:00.000+01:00
diff --git a/articles/app-service/configure-language-java-data-sources.md b/articles/app-service/configure-language-java-data-sources.md
@@ -41,7 +41,7 @@ For more information, see the [Spring Boot documentation on data access](https:/
 ::: zone pivot="java-tomcat"
 
 > [!TIP]
-> By default, the Linux Tomcat containers can automatically configure shared data sources for you in the Tomcat server. The only thing for you to do is add an app setting that contains a valid JDBC connection string to an Oracle, SQL Server, PostgreSQL, or MySQL database (including the connection credentials), and App Service automatically adds the cooresponding shared database to */usr/local/tomcat/conf/context.xml* for you, using an appropriate driver available in the container. For an end-to-end scenario using this approach, see [Tutorial: Build a Tomcat web app with Azure App Service on Linux and MySQL](tutorial-java-tomcat-mysql-app.md).
+> By default, the Linux Tomcat containers can automatically configure shared data sources for you in the Tomcat server. The only thing for you to do is add an app setting that contains a valid JDBC connection string to an Oracle, SQL Server, PostgreSQL, or MySQL database (including the connection credentials), and App Service automatically adds the corresponding shared database to */usr/local/tomcat/conf/context.xml*, using an appropriate driver available in the container. For an end-to-end scenario using this approach, see [Tutorial: Build a Tomcat web app with Azure App Service on Linux and MySQL](tutorial-java-tomcat-mysql-app.md).
 
 These instructions apply to all database connections. You 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.
 
@@ -377,44 +377,104 @@ az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar
 
 ::: zone pivot="java-jboss"
 
-There are three core steps when [registering a data source with JBoss EAP](https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html/configuration_guide/datasource_management): uploading the JDBC driver, adding the JDBC driver as a module, and registering the module. App Service is a stateless hosting service, so the configuration commands for adding and registering the data source module must be scripted and applied as the container starts.
+> [!TIP]
+> By default, the Linux JBoss containers can automatically configure shared data sources for you in the JBoss server. The only thing for you to do is add an app setting that contains a valid JDBC connection string to an Oracle, SQL Server, PostgreSQL, or MySQL database (including the connection credentials), and App Service automatically adds the corresponding shared data source, using an appropriate driver available in the container. For an end-to-end scenario using this approach, see [Tutorial: Build a JBoss web app with Azure App Service on Linux and MySQL](tutorial-java-jboss-mysql-app.md).
+
+There are three core steps when [registering a data source with JBoss EAP](https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.0/html/configuration_guide/datasource_management): 
+
+1. Upload the JDBC driver.
+1. Add the JDBC driver as a module.
+1. Add a data source with the module. 
 
-1. Obtain your database's JDBC driver.
-2. Create an XML module definition file for the JDBC driver. The following example shows a module definition for PostgreSQL.
+App Service is a stateless hosting service, so you must put these steps into a startup script and run it each time the JBoss container starts. Using PostgreSQL as an example:
+
+1. Create an XML module definition file for the JDBC driver. The following example shows a module definition for PostgreSQL called *postgresql-module.xml*.
 
     ```xml
     <?xml version="1.0" ?>
-    <module xmlns="urn:jboss:module:1.1" name="org.postgres">
-        <resources>
-        <!-- ***** IMPORTANT : REPLACE THIS PLACEHOLDER *******-->
-        <resource-root path="/home/site/deployments/tools/postgresql-42.2.12.jar" />
-        </resources>
-        <dependencies>
-            <module name="javax.api"/>
-            <module name="javax.transaction.api"/>
-        </dependencies>
+    <module xmlns="urn:jboss:module:1.1" name="org.postgresql">
+      <resources>
+        <resource-root path="postgresql-42.7.1.jar" />
+      </resources>
+      <dependencies>
+        <module name="javax.api" />
+        <module name="javax.transaction.api" />
+      </dependencies>
     </module>
     ```
 
-1. Put your JBoss CLI commands into a file named `jboss-cli-commands.cli`. The JBoss commands must add the module and register it as a data source. The following example shows the JBoss CLI commands for PostgreSQL.
+1. Put your JBoss CLI commands into a file named *jboss-cli-commands.cli*. The JBoss commands must add the module and register it as a data source. The following example shows the JBoss CLI commands for creating a PostgreSQL data source with the JNDI name `java:jboss/datasources/postgresDS`.
 
     ```bash
-    #!/usr/bin/env bash
-    module add --name=org.postgres --resources=/home/site/deployments/tools/postgresql-42.2.12.jar --module-xml=/home/site/deployments/tools/postgres-module.xml
+    #!/bin/bash
+    # These commands are executed by the JBoss CLI.
+    module add --name=org.postgresql --resources=/home/site/libs/postgresql-42.7.1.jar --module-xml=/home/site/scripts/postgresql-module.xml
+    /subsystem=datasources/jdbc-driver=postgresql:add(driver-name="postgresql",driver-module-name="org.postgresql",driver-class-name="org.postgresql.Driver",driver-xa-datasource-class-name="org.postgresql.xa.PGXADataSource")
+    data-source add --name="PostgresqlDS" --driver-name="postgresql" --jndi-name="java:jboss/datasources/postgresDS" --connection-url="jdbc:postgresql://${env.DB_HOST}:5432/postgres" --user-name="${env.DB_USERNAME}" --password="${env.DB_PASSWORD}" --enabled=true --use-java-context=true
+    ```
+
+    Note that the `module add` command uses three environment variables (`DB_HOST`, `DB_USERNAME`, and `DB_PASSWORD`), which you must add in App Service as app settings.
 
-    /subsystem=datasources/jdbc-driver=postgres:add(driver-name="postgres",driver-module-name="org.postgres",driver-class-name=org.postgresql.Driver,driver-xa-datasource-class-name=org.postgresql.xa.PGXADataSource)
+1. Create a startup script, *startup.sh*, that calls the JBoss CLI commands. The following example shows how to call your `jboss-cli-commands.cli`. Later, you'll configure App Service to run this script when the container starts.
 
-    data-source add --name=postgresDS --driver-name=postgres --jndi-name=java:jboss/datasources/postgresDS --connection-url=${POSTGRES_CONNECTION_URL,env.POSTGRES_CONNECTION_URL:jdbc:postgresql://db:5432/postgres} --user-name=${POSTGRES_SERVER_ADMIN_FULL_NAME,env.POSTGRES_SERVER_ADMIN_FULL_NAME:postgres} --password=${POSTGRES_SERVER_ADMIN_PASSWORD,env.POSTGRES_SERVER_ADMIN_PASSWORD:example} --use-ccm=true --max-pool-size=5 --blocking-timeout-wait-millis=5000 --enabled=true --driver-class=org.postgresql.Driver --exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter --jta=true --use-java-context=true --valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
+    ```bash
+    $JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/scripts/jboss_cli_commands.cli --resolve-parameter-values
     ```
 
-1. Create a startup script, `startup_script.sh` that calls the JBoss CLI commands. The following example shows how to call your `jboss-cli-commands.cli`. Later, you'll configure App Service to run this script when the container starts.
+1. Using a deployment option of your choice, upload your JDBC driver, *postgresql-module.xml*, *jboss-cli-commands.cli*, and *startup.sh* to the paths specified in the respective scripts. Especially, upload *startup.sh* as a startup file. For example:
 
-    ```bash
-    $JBOSS_HOME/bin/jboss-cli.sh --connect --file=/home/site/deployments/tools/jboss-cli-commands.cli
+# [Azure CLI](#tab/cli)
+
+    ```azurecli-interactive
+    export RESOURCE_GROUP_NAME=<resource-group-name>
+    export APP_NAME=<app-name>
+
+    # The lib type uploads to /home/site/libs by default
+    az webapp deploy --resource-group $RESOURCE_GROUP_NAME --name $APP_NAME --src-path postgresql-42.7.1.jar --target-path postgresql-42.7.1.jar --type lib
+    az webapp deploy --resource-group $RESOURCE_GROUP_NAME --name $APP_NAME --src-path postgresql-module.xml --target-path /home/site/scripts/postgresql-module.xml --type static
+    az webapp deploy --resource-group $RESOURCE_GROUP_NAME --name $APP_NAME --src-path jboss_cli_commands.cli --target-path /home/site/scripts/jboss_cli_commands.cli --type static
+    # The startup type uploads to /home/site/scripts by default and sets it up to run on startup
+    az webapp deploy --resource-group $RESOURCE_GROUP_NAME --name $APP_NAME --src-path startup.sh --type startup
+    ```
+
+For more information, see [Deploy files to App Service](deploy-zip.md).
+
+# [Azure Maven Plugin](#tab/maven)
+
+    ```xml
+    <deployment>
+        <resources>
+            <resource>
+                <!-- The lib type uploads to /home/site/libs by default -->
+                <type>lib</type>
+                <directory>${project.basedir}/src/main/jboss/config</directory>
+                <includes>
+                    <include>postgresql-42.7.1.jar</include>
+                </includes>
+            </resource>
+            <resource>
+                <!-- The script type uploads to /home/site/scripts by default -->
+                <type>script</type>
+                <directory>${project.basedir}/src/main/jboss/config</directory>
+                <includes>
+                    <include>postgresql-module.xml</include>
+                    <include>jboss_cli_commands.cli</include>
+                </includes>
+            </resource>
+            <resource>
+                <!-- The startup type uploads to /home/site/scripts by default and sets it up to run on startup -->
+                <type>startup</type>
+                <directory>${project.basedir}/src/main/jboss/config</directory>
+                <includes>
+                    <include>startup.sh</include>
+                </includes>
+            </resource>
+            ...
+        </resources>
+    </deployment>
     ```
 
-1. Using an FTP client of your choice, upload your JDBC driver, `jboss-cli-commands.cli`, `startup_script.sh`, and the module definition to `/site/deployments/tools/`.
-2. Configure your site to run `startup_script.sh` when the container starts. In the Azure portal, navigate to **Configuration** > **General Settings** > **Startup Command**. Set the startup command field to `/home/site/deployments/tools/startup_script.sh`. **Save** your changes.
+---
 
 To confirm that the datasource was added to the JBoss server, SSH into your webapp and run `$JBOSS_HOME/bin/jboss-cli.sh --connect`. Once you're connected to JBoss, run the `/subsystem=datasources:read-resource` to print a list of the data sources.
 
diff --git a/articles/app-service/configure-language-java-deploy-run.md b/articles/app-service/configure-language-java-deploy-run.md
@@ -429,7 +429,7 @@ To improve performance of Tomcat applications, you can compile your JSP files be
 
 App Service allows users to choose the major version of the JVM, such as Java 8 or Java 11, and the patch version, such as 1.8.0_232 or 11.0.5. You can also choose to have the patch version automatically updated as new minor versions become available. In most cases, production apps should use pinned patch JVM versions. This prevents unanticipated outages during a patch version autoupdate. All Java web apps use 64-bit JVMs, and it's not configurable.
 
-::: zone pivot="java-jboss"
+::: zone pivot="java-tomcat"
 
 If you're using Tomcat, you can choose to pin the patch version of Tomcat. On Windows, you can pin the patch versions of the JVM and Tomcat independently. On Linux, you can pin the patch version of Tomcat; the patch version of the JVM is also pinned but isn't separately configurable.
 
@@ -439,6 +439,24 @@ If you choose to pin the minor version, you need to periodically update the JVM
 
 ::: zone pivot="java-jboss"
 
+## Run JBoss CLI
+
+In your JBoss app's SSH session, you can run the JBoss CLI as usual. For example:
+
+```
+$JBOSS_HOME/bin/jboss-cli.sh --connect
+```
+
+Depending on where JBoss is in the server lifecycle, you may not be able to connect. Wait a few minutes and try again. Note also that changes you make to the server with JBoss CLI doesn't persist after the app restarts. This approach is useful for quick checks of your current server state (for example, to see if a data source is properly configured).
+
+The most reliable way to run JBoss CLI and persist your server changes is running it inside a startup script or a startup command. To do this, upload a file directly as a startup script. For an end-to-end example, see [Configure data sources for a Tomcat, JBoss, or Java SE app in Azure App Service](configure-language-java-data-sources.md&pivots=java-jboss).
+
+Alternatively, you can manually configure App Service to run any file on startup. For example:
+
+```azurecli-interactive
+az webapp config set --resource-group <group-name> --name <app-name> --startup-file /home/site/scripts/foo.sh
+```
+
 ## Clustering
 
 App Service supports clustering for JBoss EAP versions 7.4.1 and greater. To enable clustering, your web app must be [integrated with a virtual network](overview-vnet-integration.md). When the web app is integrated with a virtual network, it restarts, and the JBoss EAP installation automatically starts up with a clustered configuration. The JBoss EAP instances communicate over the subnet specified in the virtual network integration, using the ports shown in the `WEBSITES_PRIVATE_PORTS` environment variable at runtime. You can disable clustering by creating an app setting named `WEBSITE_DISABLE_CLUSTERING` with any value.
