From 944958f016e005762111fb664a4775b7fe582989 Mon Sep 17 00:00:00 2001 From: David Mueller Date: Thu, 31 Aug 2023 15:29:55 -0400 Subject: [PATCH] create new pages #4746 --- .../pages/configure-spring-boot-actuator.adoc | 191 +++++++++++++++++ modules/ROOT/pages/deploy-spring-boot.adoc | 193 ++++++++++++++++++ .../pages/command/springbootUtility-thin.adoc | 2 + .../pages/feature/springBoot/description.adoc | 6 +- 4 files changed, 390 insertions(+), 2 deletions(-) create mode 100644 modules/ROOT/pages/configure-spring-boot-actuator.adoc create mode 100644 modules/ROOT/pages/deploy-spring-boot.adoc diff --git a/modules/ROOT/pages/configure-spring-boot-actuator.adoc b/modules/ROOT/pages/configure-spring-boot-actuator.adoc new file mode 100644 index 0000000000..dad4913705 --- /dev/null +++ b/modules/ROOT/pages/configure-spring-boot-actuator.adoc @@ -0,0 +1,191 @@ +// Copyright (c) 2023 IBM Corporation and others. +// Licensed under Creative Commons Attribution-NoDerivatives +// 4.0 International (CC BY-ND 4.0) +// https://creativecommons.org/licenses/by-nd/4.0/ +// +// Contributors: +// IBM Corporation +// +:page-description: You can change the HTTP endpoint, virtual host, and other settings for the Spring Boot Actuator so that it uses values other than the defaults for Liberty. +:seo-title: Configuring non-default settings for the Spring Boot Actuator +:page-layout: general-reference +:page-type: general += Configuring non-default settings for the Spring Boot Actuator + +You can change the HTTP endpoint, virtual host, and other settings for the so that it uses values other than the defaults for Liberty. When you are not using the default HTTP endpoint and default virtual host, Open Liberty provides a set of configuration IDs to configure a web server for a Spring Boot application. + +By default, the main web server for a Spring Boot application uses the Open Liberty default HTTP endpoint and the virtual host when the Spring Boot application is deployed to Open Liberty. Open Liberty defines the main web server as the first server that is created for the root Spring Boot `ApplicationContext` class. When the Spring Boot application uses the default HTTP endpoint and virtual host, the Spring Boot application properties that are used to configure the main web server are ignored. The Open Liberty configuration settings for the default HTTP endpoint and default virtual host are used instead. All other Spring Boot application web server instances use the settings that are specified by the application. For example, you can use link:https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html[Spring Boot Actuators] on a different port than the main web server port by configuring the `management.server.port` application property. + +You can override the use of the Open Liberty default HTTP endpoint and default virtual host for the main web server by setting the `server.liberty.use-default-host application` property to `false` in the `applicationArgument` element. + +[source,xml] +---- + + --server.liberty.use-default-host=false + +---- + +This configuration uses the Spring Boot application properties to configure the main web server instead of the Open Liberty defaults. + +== Open Liberty Spring Boot configuration IDs + +When you are not using the default HTTP endpoint and default virtual host, Open Liberty provides a set of configuration IDs to configure a web server for a Spring Boot application. Use these configuration IDs in the`server.xml`file to override application settings for the web server. The IDs are ordered by precedence by using the `springBootVirtualHost-` ID that overrides all server endpoint settings with configuration from the server `server.xml` file. You can specify these IDs on different `server.xml` configuration elements to define the values for the web server for a Spring Boot application. The `` value is the HTTP port that the Spring Boot application requests. + + +springBootVirtualHost--:: +Set this ID on the config:virtualHost element to configure the virtual host host for the server to use a specified alias. + +springBootHttpEndpoint-:: +Set this ID on the config:httpEndpoint element to configure the HTTP endpoint for the server to use a specified host address and HTTP port. + +springBootSsl-:: +Set this ID on the config:ssl element to configure SSL settings for the HTTP endpoint. + +springBootKeyStore-:: +Set this ID on the config:keyStore element to configure the keystore for the SSL settings. + +springBootTrustStore-:: +Set this ID on the config:keyStore element to configure the truststore for the SSL settings. + +The examples in the following sections demonstrate how to specify these configuration IDs. + +== Configuration examples + +The following examples use the sample `hellospringboot.jar` application that you deploy to Open Liberty in xref:deploy-spring-boot.adoc[Configure and Deploy Spring Boot applications to Open Liberty]. Spring Boot properties sometimes change between versions. The following examples use Spring Boot 3.x properties. + +- <<#nondefault, Configuring a non-default virtual host and HTTP endpoint for a Spring Boot application and the Spring Boot Actuator>> +- <<#port, Configuring an HTTP port for the Spring Boot Actuator>> +- <<#http, Configure the HTTP endpoint for the Actuator and enable access logging>> +- <<#tls,Override the default Transport Layer Security (TLS) settings for the Spring Boot Actuator>> + +[#nondefault] +=== Configuring a non-default virtual host and HTTP endpoint for a Spring Boot application and the Spring Boot Actuator + +In the example, the `hellospringboot.jar` application that is deployed to Liberty is configured so that it does not use the Liberty default HTTP endpoint or default virtual host. From the application HTTP port, you configure the application to use a different HTTP port for the actuator. Then, use the `server.xml file` to override the server settings for the actuator. + +1. Configure the `springBootApplication` element in the `server.xml` file to override the default HTTP endpoint and default virtual host. ++ +a. Add a command line argument for the application by using the `applicationArgument` element. Pass the `--server.liberty.use-default-host=false` argument. ++ +[source,xml] +---- + + --server.liberty.use-default-host=false + +---- +b. Start the server in the foreground by running the `server run helloserver` command. +c. Test the application in a browser by going to the http://localhost:8080 URL. +d. Test the actuator health endpoint at the http://localhost:8080/health URL. + +2. To configure a non-default port for the actuator input, pass the `--management.server.port=9999` argument. ++ +[source,xml] +---- + + --server.liberty.use-default-host=false + --management.server.port=9999 + +---- ++ +a. Test the application at the http://localhost:8080 URL. +b. Test the actuator health endpoint at the http://localhost:9999/health URL. +c. Stop the server with the `server stop helloserver` command. + +[#port] +=== Configuring an HTTP port for the Spring Boot Actuator + +1. For the actuator to use the HTTP port 9080 endpoint by default, configure a `virtualHost` element with the `springBootVirtualHost-9999` configuration ID. ++ +[source,xml] +---- + + *:9080 + +---- +2. Start the server in the foreground with the server run helloserver command. +3. Test the application at the http://localhost:8080 URL. +4. Test the actuator health endpoint at the http://localhost:9080/health URL. +5. Stop the server with the `server stop helloserver` command. +6. Remove the `virtualHost` configuration from the `server.xml` file. + +[#http] +=== Configure the HTTP endpoint for the Actuator and enable access logging + +1. Specify the `springBootHttpEndpoint` configuration ID for the `httpEndpoint` element and add the `accessLogging` element. ++ +[source,xml] +---- + + + +---- +2. Start the server in the foreground by running the the `server run` command from the `wlp/bin` directory. ++ +---- +server run helloserver +---- + +3. Test the application in a browser by going to the http://localhost:8080 URL. +4. Test the actuator health endpoint in a browser by going to the http://localhost:9999/health URL. +5. Check the `/usr/servers/helloserver/logs/http_access.log` file for reports about accessing the health actuator. +6. Stop the server with the server stop helloserver command. + +[#tls] +=== Override the default Transport Layer Security (TLS) settings for the Spring Boot Actuator + +You can use the `springBootVirtualHost-8080` and `springBootHttpEndpoint-8080` configuration IDs to override the server settings for the main server of the application. Similarly, you can override the TLS settings that the actuator endpoints use, but overriding requires that the application includes configured TLS settings for the actuator server. Assume that the actuator TLS settings are set with the following values in the `server.xml` file and that the application contains a `server-keystore.p12` keystore file and a `server-truststore.p12` truststore file on the class path. + +[source,xml] +---- + + pages-3.1 + springBoot-3.0 + transportSecurity-1.0 + + + + --server.liberty.use-default-host=false + --management.server.port=9999 + --management.server.ssl.key-store=classpath:server-keystore.p12 + --management.server.ssl.key-store-password=secret + --management.server.ssl.key-password=secret + --management.server.ssl.trust-store=classpath:server-truststore.p12 + --management.server.ssl.trust-store-password=secret + +--- + +- Override the SSL settings by specifying the `springBootSsl-9999` configuration ID. +a. If the `httpEndpoint` element exists, remove it from the `server.xml` file with the `springBootHttpEndpoint-9999` ID. +b. Override the SSL settings that the actuator uses. ++ +[source,xml] +---- + + + +---- + +c. Start the server in the foreground with the server run helloserver command. +d. Test the application at the http://localhost:8080 URL. +e. Test the actuator health endpoint at the secure http://localhost:9999/health URL. +f. Stop the server with the `server stop helloserver` command. ++ +If the application was configured to use SSL, you can use the `springBootSsl-9999` ID in the previous steps to override the SSL settings for the main server of the application. + +- Override the individual keystore or truststore by specifying the `springBootKeyStore-9999` or `springBootTrustStore-9999` IDs. +a. If the `httpEndpoint` element exists, remove it from the `server.xml` file with the `springBootHttpEndpoint-9999` ID. +b. If the `ssl` and `keyStore` elements exist, remove them from the `server.xml` file with the `springBootSsl-9999` ID. +c. Add one or both lines of code to override the keystore or truststore that the actuator uses. ++ +[source,xml] +---- + + +---- + +d. Start the server in the foreground with the `server run helloserver` command. +e. Test the application at the http://localhost:8080 URL. +f. Test the actuator health endpoint at the secure https://localhost:9999/health URL. +g. Stop the server with the `server stop helloserver` command. ++ +If the server was configured to use SSL, you can use the `springBootKeyStore-8080` and `springBootTrustStore-8080` IDs in the previous steps to override the TLS settings for the main server of the application. diff --git a/modules/ROOT/pages/deploy-spring-boot.adoc b/modules/ROOT/pages/deploy-spring-boot.adoc new file mode 100644 index 0000000000..9b4aa1e43c --- /dev/null +++ b/modules/ROOT/pages/deploy-spring-boot.adoc @@ -0,0 +1,193 @@ +// Copyright (c) 2023 IBM Corporation and others. +// Licensed under Creative Commons Attribution-NoDerivatives +// 4.0 International (CC BY-ND 4.0) +// https://creativecommons.org/licenses/by-nd/4.0/ +// +// Contributors: +// IBM Corporation +// +:page-description: You can enable Open Liberty to support a Spring Boot application. Open Liberty can also configure Spring Boot application arguments and properties and can also thin Spring Boot applications to use resources efficiently. +:seo-title: Deploy Spring Boot applications to Open Liberty +:page-layout: general-reference +:page-type: general += Configure and Deploy Spring Boot applications to Open Liberty + +You can enable Open Liberty to support a Spring Boot application. Open Liberty can also configure Spring Boot application arguments and properties and provides tools that optimize the deployment of Spring Boot applications to containers. + +To enable Liberty to support a Spring Boot application, add one of the feature:springBoot[display=Spring Boot Support] features to your `server.xml` file. When you deploy a Spring Boot application, Liberty disables the web container that is embedded in the application and uses the Liberty web container instead. You can deploy one Spring Boot application for each server configuration. + +The examples in the following sections use a sample application that is called `hellospringboot.jar` that is based on the finished application from the link:https://spring.io/guides/gs/spring-boot/[Building an Application with Spring Boot] guide. If you are not familiar with Spring Boot, complete that guide first. The guide includes instructions to build the application as an executable JAR, which is the file format that is used in these examples. + +- <<#deploy,Deploying a Spring Boot application to Open Liberty from the command line>> +- <<#define,Defining Spring Boot application argument>> +- <<#thin,Configuring thin Spring Boot applications>> + +[#deploy] +== Deploying a Spring Boot application to Open Liberty from the command line + +This procedure uses an example application to show how to deploy a Spring Boot application by manually configuring your `server.xml` file and running the server from the command line. To deploy a Spring Boot application to Open Liberty by using Maven, see the link:/guides/spring-boot.html[Containerizing, packaging, and running a Spring Boot application] guide. + +In the following steps, you create a Liberty server instance, deploy your Spring Boot JAR application, and specify the default HTTP port for the server instance. By default, Liberty deploys the Spring Boot application with the default host configuration. The example uses the `hellospringboot.jar` sample application and `9090` for the default HTTP port. + +1. Run the `server create helloserver` command from the `wlp/bin` directory to create a server and name it `helloserver`. ++ +---- +server create helloserver +---- ++ +This command creates the `/usr/servers/helloserver/apps` directory. +2. Enable the version of the Open Liberty feature:springBoot[display=Spring Boot Suppor]t feature that your application requires by adding it to the `featureManager` element of the `server.xml` file. ++ +- If your application uses Spring Boot 1.5.8, enable the `springBoot-1.5` feature. +- If your application uses Spring Boot 2.0.1, enable the `springBoot-2.0` feature. +- If your application uses Spring Boot 3.x, enable the `springBoot-3.0` feature. ++ +The `hellospringboot.jar` application uses the `spring-boot-starter-web` dependency, which also requires you to enable a feature:servlet[display=Servlet] feature, as shown in the following `server.xml` file example: ++ +[source,xml] +---- + + springBoot-3.0 + servlet-6.0 + +---- + +3. Copy the `hellospringboot.jar` application into the `/usr/servers/helloserver/apps` directory that the `server create` command created. +4. Configure the application by updating the `server.xml` file. ++ +- Specify the application location with a config:springBootApplication[] element. +- Configure the HTTP port for the default host to `9090` by replacing the `httpPort="9080"` attribute value with an `httpPort="9090"` attribute value. ++ +[source,xml] +---- + + +---- +5. Start the server in the foreground by running the `server run` command: ++ +---- +server run helloserver +---- +6. Test the application by visiting the http://localhost:9090 URL in a browser. + +You deployed a Spring Boot sample application to Open Liberty. When you finish testing the application, run the `server stop` command. + +---- +server stop helloserver +---- + +[#define] +== Defining Spring Boot application arguments + +When you deploy a Spring Boot application to Open Liberty, you can configure application arguments to override the application property defaults. The following example uses the sample `hellospringboot.jar` application that you deployed to Open Liberty in <<#deploy,the previous section>>. + +When you start a Spring Boot application from the command line as an executable JAR file, you start with a list of command-line arguments, as shown in the following example. + +---- +java -jar hellospringboot.jar --server.servlet.context-path=/mypath --myapp.arg=true +---- + +By default, the `SpringApplication` Spring Boot class converts any command-line argument that starts with dashes (`--`) to a property and adds it to the Spring Environment. + +When you deploy a Spring Boot application to Liberty, you can configure the command-line argument for the application with the `applicationArgument` element within the `springBootApplication` element. Use these elements when you want to override application property defaults that are included in the Spring Boot application. + +In the following example, the `hellospringboot.jar` Spring Boot application deployment to Open Liberty is configured to pass multiple command-line arguments. The two properties that are used in the example are the Spring Boot application properties for configuring the `server.servlet.context-path` application context path and the `spring.mvc.servlet.path` Spring dispatcher servlet path. + +For more information, see link:https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#appendix.application-properties[Spring Boot common application properties]. + +1. Find the `springBootApplication` element in the `server.xml` file of the `helloserver` server that you created in the previous section. ++ +[source,xml] +---- + +---- + +2. Add a command-line argument for the application with the `applicationArgument` element and pass the `--server.servlet.context-path=/testpath1` argument to change the application context root to `/testpath1`, as shown in the following example. ++ +[source,xml] +---- + + --server.servlet.context-path=/testpath1 + +---- + +3. Start the server in the foreground by running the `server run` command. ++ +[source,xml] +---- +server run helloserver +---- + +4. Test the application in a browser by going to the http://localhost:9090/testpath1 URL. + +5. Without stopping the server, change the context path to `testpath2`. ++ +[source,xml] +---- + + --server.servlet.context-path=/testpath2 + +---- + +6. Test the application in a browser by going to the http://localhost:9090/testpath2 URL. + +7. Without stopping the server, add another application argument in a new `applicationArgument` element, as shown in the following example. ++ +[source,xml] +---- + + --server.context-path=/testpath2 + --server.servlet-path=/mydispatcher + +---- ++ +The Spring Boot application stops and restarts with the same context path. + +8. Test the application in a browser by going to the http://localhost:9090/testpath2/mydispatcher URL. + +[#thin] +== Configuring thin Spring Boot applications + +You can thin a Spring Boot application to create efficient container layers and use resources efficiently. + +A Spring Boot application JAR or WAR file is a self-contained artifact. It packages all of the application dependencies inside the final artifact alongside the application content, including an embedded server implementation, such as Tomcat, Jetty, or Undertow. The result is a fat artifact that is easy to run on any server that has a JVM. It also results in a large artifact, even for the smallest `hello world` Spring Boot web application. + +With a microservices architecture, the application content that is included in a Spring Boot application JAR file can be much smaller than the Spring Boot framework dependencies. A large application JAR file might be costly to deploy if your application needs frequent updates. For example, if you use Docker to deploy your application to the cloud, you need to build a new Docker layer that includes your updated application content. This new Docker layer contains the updated fat JAR file, which contains both your application content and all of the Spring Boot framework dependencies. THis process results in large Docker layers for updating your application in the cloud. + +Open Liberty can create efficient Docker layers for your application updates and use resources efficiently when you deploy frequent updates to your microservice applications in the cloud. + +The following example uses the `springBootUtility thin` command to separate the Spring Boot application content from the dependencies that are packaged inside of the Spring Boot application, thinning the Spring Boot application. For more information, see the xref:reference:command/springBootUtility-thin.adoc[springBootUtility thin] command. + + +1. Configure the thin Spring Boot application JAR file and the library dependencies. ++ +a. Deploy the `hellospringboot.jar` application as explained in the <<#deploy,Deploying a Spring Boot application to Open Liberty>> section. +b. Deploy the library dependencies to the `wlp/usr/shared/resources/lib.index.cache/` directory. + +2. Run the `springBootUtility thin` command with the necessary options to create the thin Spring Boot application in the correct `dropins` folder of the `helloserver` server configuration and to cache the dependencies to the `usr/shared/resources/lib.index.cache` directory. ++ +The following example assumes you are running the command from the directory that contains the top-level `wlp` Open Liberty runtime directory. ++ +---- +wlp/bin/springBootUtility thin \ + --sourceAppPath=hellospringboot.jar \ + --targetLibCachePath=wlp/usr/shared/resources/lib.index.cache \ + --targetThinAppPath=wlp/usr/servers/helloserver/dropins/spring/hellospringboot.jar +---- ++ +For more information about the available command-line options, see the xref:reference:command/springBootUtility-thin.adoc[springBootUtility thin] command. + +3. Start the server in the foreground by running the `server run` command. ++ +[source,xml] +---- +server run helloserver +---- + +4. Test the application in a browser by going to the `http://localhost:9080` URL. +The default HTTP endpoint is used to service the application. + +== See also +- Guide: link:/guides/spring-boot.html[Containerizing, packaging, and running a Spring Boot application] +- xref:configure-spring-boot-actuator.adoc[Configuring non-default settings for the Spring Boot Actuator] +- xref:reference:command/springBootUtility-commands.adoc[springBootUtility commands] diff --git a/modules/reference/pages/command/springbootUtility-thin.adoc b/modules/reference/pages/command/springbootUtility-thin.adoc index 703193830f..e15b374fea 100644 --- a/modules/reference/pages/command/springbootUtility-thin.adoc +++ b/modules/reference/pages/command/springbootUtility-thin.adoc @@ -14,6 +14,8 @@ The `springBootUtility thin` command creates a thin application and library cach This command stores the dependent library JAR files of the application to the target library cache and packages the remaining application artifacts into a thin application JAR file. When a read-only parent library cache is specified, the command creates a target library cache that contains only the libraries that are not available in the parent cache. This action creates efficient container layers for Spring Boot applications. +For more information about thin Spring Boot applications, see xref:ROOT:deploy-spring-boot.adoc#thin[Configuring thin Spring Boot applications]. + == Usage examples Create the thin Spring Boot application with the `springBootUtility thin` command and the necessary options: diff --git a/modules/reference/pages/feature/springBoot/description.adoc b/modules/reference/pages/feature/springBoot/description.adoc index f4f63b9e7e..dbc0d797ce 100644 --- a/modules/reference/pages/feature/springBoot/description.adoc +++ b/modules/reference/pages/feature/springBoot/description.adoc @@ -1,4 +1,6 @@ -Open Liberty support for Spring Boot is integrated with support for the web container by using the feature:servlet[display=Java Servlets -] and feature:jsp[display=JavaServer Pages] features. The feature:transportSecurity[display=Transport Security] or feature:websocket[display=Java WebSocket] features can be enabled if HTTPS or WebSocket support is needed. All other server configuration is handled by Spring Boot application properties. +Open Liberty support for Spring Boot is integrated with support for the web container by using the feature:servlet[display=Jakarta Servlets +] and feature:pages[display=Jakarta Server Pages] features. The feature:transportSecurity[display=Transport Security] or feature:websocket[display=Jakarta WebSocket] features can be enabled if HTTPS or WebSocket support is needed. All other server configuration is handled by Spring Boot application properties. For example, security properties can be set by using `spring.security.*` application properties. The Open Liberty Spring Boot feature does not integrate with the functions that are provided by other Liberty features, such as feature:appSecurity[display=Application Security] and feature:restfulWS[display=Jakarta Restful Services]. If an application needs functions similar to what is provided by these Open Liberty features, the Spring Boot project provides Spring Boot starters that can be included in the application. Including Spring Boot starters like https://spring.io/guides/gs/securing-web[spring-boot-starter-security] or third-party starters like https://cxf.apache.org/docs/springboot.html[cxf-spring-boot-starter-jaxrs] in an application allows it to use technologies that are provided by the starter instead of using Liberty features. + +For more information, see xref:ROOT:deploy-spring-boot.adoc[Configure and Deploy Spring Boot applications to Open Liberty].