Deploying springBoot applications

dmuelle commented 3 years ago

Found this comment from @tjwatson in a closed issue

The springBootUtility thin command doesn't make much sense without the information about why spring boot applications should be thinned: https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_thin_sb_applications.html

We either need to put this information in with the springbootUtility documentation or it needs to be a separate section under DEPLOYMENT. My preference would be to have this information in a separate section under DEPLOYMENT.

The topic was never moved over. We also have this comment from Laura/ Alasdair in the KC tracking sheet:

Low priority. While this is relevant, the Open Liberty microservices strategy is MicroProfile so we shouldn't undermine/confuse it by pushing Spring as high priority. Also, the target audience for the current Spring work is people already on WebSphere whose developers want to work with Spring apps. So not our primary audience either.

Analyze the entire Deploying a Spring Boot application to Liberty section and see what might go into a single OL topic in the deployment section, possibly with config examples added to the Spring Boot Support feature- but noten that the IBM docs topic uses v 1.5 and 2.0 is current so need to confirm if any changes from the IBM docs examples

dmuelle commented 1 year ago

moving to 23.0.0.8 to align with the planned sb3 feature release

dmuelle commented 1 year ago

epic moved to 23.0.0.9

Issue to update the guide for sb3

dmuelle commented 1 year ago

Plan to document (single topic and possibly config examples on feature page):

Overview of deploying SB app to OL
Link to guide, possibly include manual deploy steps
reference for Defining Spring Boot application arguments Spring Boot application properties Configuring the HTTP endpoint and virtual host for the Spring Boot Actuator Configuring thin Spring Boot applications

dmuelle commented 1 year ago

topics to migrate:

Deploying a Spring Boot application to Liberty Defining Spring Boot application arguments Spring Boot application properties Configuring the HTTP endpoint and virtual host for the Spring Boot Actuator Configuring thin Spring Boot applications We can also move the table/ info from https://www.ibm.com/docs/en/was-liberty/base?topic=architecture-spring-boot-programming-model-support and make any needed edits

dmuelle commented 1 year ago

Hi @hlhoots @cbridgha - I've got drafts of the migrated and updated Spring Boot topics for OL. I think these need careful review as some of the source material was fairly convoluted and in some cases hadn't been updated since SN 1.5

Configure and Deploy Spring Boot applications to Open Liberty: covers basic JAR deployment from CLI with a helloworld app, specifying command-line args in server.xml config, and creating Thin SB app w/ springbootUtility
Configuring non-default settings for the Spring Boot Actuator- the source for this was really confusing and hadn't been updated since 1.5. Needs testing
Spring Boot Support feature page- includes info about integration with different OL features and various spring boot starters. Note that the 3.0 page won't be available until after we update the gen doc, but it will include corresponding info to whats there now for 1.5 and 2.0 pages.

Chuck had mentioned possibly adding some examples to show how to deploy from a WAR file, we dont have anything like that yet, though I did add clarification on the Deploying topic that you can deploy from either JAR or WAR (which we previously did not mention). Let me know what else we need to add around that.

UPDATE: Added examples and mentions throughout the docs to clarify that the Open Liberty configuration is the same for JAR vs WAR file

Thanks!

tjwatson commented 1 year ago

Not sure how this gets populated, but for https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/springBoot-1.5.html it lists the Supported Java versions including JavaSE-1.8 - JavaSE-20. While Spring Boot 1.5 only supports JavaSE-1.8

tjwatson commented 1 year ago

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.0.4, enable the springBoot-3.0 feature.

We need to clarify that the springBoot-X.Y support versions of Spring Boot X.Y up to, but not including (X-1).0

If I was doing this with proper mathematical range notation that would be:

If your application uses Spring Boot [1.5.8, 2.0), enable the springBoot-1.5 feature.
If your application uses Spring Boot [2.0.1, 3.0), enable the springBoot-2.0 feature.
If your application uses Spring Boot [3.0.4, 4.0), enable the springBoot-3.0 feature.

But maybe simply putting a + after is enough and it is obvious that springBoot-1.5 doesn't support Spring Boot 2 applications:

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.0.4+, enable the springBoot-3.0 feature.

tjwatson commented 1 year ago

For the section Configuring thin Spring Boot applications it has an example of calling springBootUtility thin where it specifies the --targetThinAppPath to be placed in the dropins/spring folder. This makes it seem that the thinned resulting JAR must be deployed to dropins/spring.

I would rather use a command like this that places the thinned result into the apps/ folder:

wlp/bin/springBootUtility thin \
    --sourceAppPath=full_path_to/wlp/usr/servers/helloserver/apps/hellospringboot.jar \
    --targetLibCachePath=full_path_to/wlp/usr/shared/resources/lib.index.cache \
    --targetThinAppPath=full_path_to/wlp/usr/servers/helloserver/apps/hellospringboot-thin.jar

And then updates the <springBootApplication location="hellospringboot.jar"> tag to point to the new hellospringboot-thin.jar location.

I recommend there also be a statement that the original apps/hellospringboot.jar can be deleted once the thinned application JAR has been created.

hlhoots commented 1 year ago

@dmuelle @cbridgha Given Tom's comments above which I am okay with if he likes that better, I just want to make sure that we have something documented about using the /dropins/spring/ folder for development without having to have the <springBootApplication> config in the server.xml. That was a function I didn't know existed until we implemented the Spring Boot 3 code.

dmuelle commented 1 year ago

@hlhoots I added a sub-section to the first part of the page specifically for using /dropins, which doesn't have you configure anything but the necessary features in server.xml:

Deploying a Spring Boot JAR or WAR application from the dropins directory

Does this cover that scenario?

dmuelle commented 1 year ago

thanks for reviewing @tjwatson

opened an issue on the dev backlog for the incorrect Java Version in v 1.5 generated page
updated Spring version listing in https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/deploy-spring-boot.html#deploy
changed thin section to not use dropins in the example: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/deploy-spring-boot.html#thin

ramkumar-k-9286 commented 1 year ago

Peer Review:

For: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/deploy-spring-boot.html#thin

You can thin a Spring Boot application to create more efficient container layers and use resources more efficiently.

Feels like efficiently is kind of repetitive. -> You can thin a Spring Boot application to create more efficient container layers and optimize resource usage.

Deploy the hellospringboot.jar or application as explained in the Deploying a Spring Boot application to Open Liberty from the command line section.

Should we be mentioning what application? -> Deploy the hellospringboot.jar or the WAR application as explained in the Deploying a Spring Boot application to Open Liberty from the command line section.

Update the server.xml file to specify the location of the thin application

Period (.) missing. -> Update the server.xml file to specify the location of the thin application.

Replace the value of the springBootApplication location element to specify the hellospringboot-thin.jar application

Period (.) missing. -> Replace the value of the springBootApplication location element to specify the hellospringboot-thin.jar application.

Replace the value of the springBootApplication location element to specify the hellospringboot-thin.jar application

Rephrased: Not sure if it implies the same. (Please verify my suggestion). -> Replace the value of the springBootApplication location element to specify the location of the hellospringboot-thin.jar application.

When an app is in the app/servers dir, the location is implied in springBootApplication location, so you dont technically specify the location, just the app file name, location is understood.

ramkumar-k-9286 commented 1 year ago

Peer Review:

For: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/deploy-spring-boot.html#deploy

To deploy a Spring Boot application to Open Liberty by using Maven, see the Containerizing, packaging, and running a Spring Boot application Open Liberty guide. -> For deploying a Spring Boot application to Open Liberty by using Maven, see the Containerizing, packaging, and running a Spring Boot application guide in Open Liberty.

I think "for deploying" is a weaker verb phrase and "Open Liberty guide" is how we generally refer to the collection

In the following steps, you create a Liberty server instance, deploy your Spring Boot JAR or WAR application, and specify the default HTTP port for the server instance. -> In the following steps, you create a Liberty server instance, deploy your Spring Boot JAR or WAR application, and specify the default HTTP port for that server instance.

There is only one server instance here, which "the" makes more clear than "that"

By default, Liberty deploys the Spring Boot application with the default host configuration. -> By default, Liberty uses the default host configuration to deploy the Spring Boot application.

not much change here and I think it reads better as is

Run the server create helloserver command from the wlp/bin directory to create a server and name it helloserver. -> From the wlp/bin directory, run the server create helloserver command to create a server named helloserver.

Specify the application location with a springBootApplication element and configure the HTTP port for the default host to 9090 by replacing the httpPort="9080" attribute value with an httpPort="9090" attribute value. -> Specify the application location by using the springBootApplication element. Configure the HTTP port for the default host as 9090 by replacing the httpPort="9080" attribute value with httpPort="9090" attribute value.

chirp1 commented 1 year ago

@dmuelle Hi David, A few minor comments...

For "This procedure uses an example application....", see if you can reword it to remove "This procedure" since the wording is self-referential. Rework anything else to have the section make sense.
For step 4 of "Deploying a Spring Boot JAR or WAR application to Open Liberty from the command line", I think it could be a little clearer so that the user doesn't have to back up and reread info that applies to the .war file example. I believe "Specify the application..." applies to both a war file and a jar file. So, leave as is. However, add a paragraph that's just a sentence for the the first example to indicate that the example is for a jar file. And then for the war file, remove the existing sentence and then add a paragraph that is a sentence to indicate that the example is for a war file.

ramkumar-k-9286 commented 1 year ago

Peer Review

Configure and Deploy Spring Boot applications to Open Liberty

Although the examples in the following sections use an example JAR application file, the Open Liberty configuration applies equally to JAR and WAR files. -> Although the following examples use a JAR application file, the Open Liberty configuration is consistent for both JAR and WAR files.

Alternatively, you can deploy a Spring Boot application without configuring the server.xml file by using the Open Liberty dropins directory. -> Alternatively, you can deploy a Spring Boot application using the Open Liberty dropins directory without configuring the server.xml file.

Test the application in a browser by going to the http://localhost:9080/ URL. -> Test the application in a browser by accessing the http://localhost:9080/ URL.

Without stopping the server, add another application argument in a new applicationArgument element to configure the Spring dispatcher servlet path, as shown in the following example. -> Without stopping the server, add another applicationArgument element to configure the Spring dispatcher servlet path, as shown in the following example.

The Spring Boot application stops and restarts with the same context path. -> The Spring Boot application is stopped and then restarted by using the same context path.

Test the application in a browser by going to the http://localhost:9090/testpath2/mydispatcher URL. -> Test the application in a browser by accessing the http://localhost:9090/testpath2/mydispatcher URL.

The result is a fat artifact that is easy to run on any server that has a JVM. However, this result is a large artifact, even for the smallest hello world Spring Boot web application. -> The result is a fat artifact that is easy to run on any server that has a JVM. However, this results in a large artifact, even for the smallest hello world Spring Boot web application.

Also, spell check: artifact or artefact ?

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 and all of the Spring Boot framework dependencies." -> For example, if you use Docker to deploy your application to the cloud, each time you update your application, you need to build a new Docker layer. This layer includes both your updated application content and all the Spring Boot framework dependencies.

Acrolinx recommends "go to" for URLs

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, which creates a thin Spring Boot application. -> The following example uses the springBootUtility thin command. This command separates the Spring Boot application content from its packaged dependencies, resulting in a thin Spring Boot application.

Run the springBootUtility thin command with the necessary options to create the hellospringboot-thin.jar thin Spring Boot application in the dropins/spring directory of the helloserver server configuration and to cache the dependencies to the usr/servers/helloserver/apps/ directory. -> Run the springBootUtility thin command with the necessary options to create the hellospringboot-thin.jar thin application in the dropins/spring directory of the helloserver server configuration and to cache the dependencies to the usr/servers/helloserver/apps/ directory. ( This is how its mentioned in Step 5 -> replaced for consistency)

Replace the value of the springBootApplication location element to specify the hellospringboot-thin.jar application. -> Replace the value of the springBootApplication location element to specify the hellospringboot-thin.jar thin application. ( This is how its mentioned in Step 5 -> replaced for consistency)

Link not working See Also: Containerizing, packaging, and running a Spring Boot application If your application uses Spring Boot 3.0.4+, enable the springBoot-3.0 feature.

Links to guides dont work on docs-draft. Spring Boot 3 link is working now that autogen is updated

ramkumar-k-9286 commented 1 year ago

Peer Review

Configuring non-default settings for the Spring Boot Actuator

The IDs are ordered by precedence by using the springBootVirtualHost-<requested port> ID that overrides all server endpoint settings with configuration from the server server.xml file. -> The IDs are ordered by precedence by using the springBootVirtualHost-<requested port> ID, which overrides all server endpoint settings with configurations from the server.xml file.

Test the actuator health endpoint at the http://localhost:8080actuator/health URL. -> Test the actuator health endpoint at the http://localhost:8080/actuator/health URL.

URL -> Please check /

If the httpEndpoint element exists, remove it from the server.xml file with the springBootHttpEndpoint-9999 ID. -> If the httpEndpoint element with the springBootHttpEndpoint-9999 ID exists, remove it from the server.xml file.

If the ssl and keyStore elements exist, remove them from the server.xml file with the springBootSsl-9999 ID. -> If the ssl and keyStore elements with the springBootSsl-9999 ID exist, remove them from the server.xml file.

Start the server in the foreground with the server run helloserver command.

Start the server in the foreground by using the server run helloserver command.

ramkumar-k-9286 commented 1 year ago

Peer Review

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/springBoot-2.0.html

This feature enables support for Spring Boot applications using Spring Boot version 2.x.x. -> This feature supports Spring Boot applications by using Spring Boot version 2.x.x.

This is from the metatype, not in manually written doc

All other server configuration is handled by Spring Boot application properties. -> All other server configurations are managed by Spring Boot application properties.

Only one server here and "configuration" is a collective noun to encompass all configuration on that server

The following table lists the Open Liberty features that are required to support certain Spring Boot 2.0 starters. -> The following table lists the Open Liberty features required to support certain Spring Boot 2.0 starters.

Per IBM style, need "that are" here

To enable the Spring Boot Support 2.0 feature, add the following element declaration into your server.xml file, inside the featureManager element: -> To enable the Spring Boot Support 2.0 feature, add the following element declaration to your server.xml file, inside the featureManager element.

This is from the metatype, not in manually written doc

dmuelle commented 1 year ago

Thanks for reviewing @chirp1 @ramkumar-k-9286 .

I implemented both of karen's suggestions. Ram, I implemented all your suggestions except for a few noted in edited comments above.

chirp1 commented 1 year ago

@dmuelle Hi David, the updates that you made based on my review comments look good to me. Thanks!

dmuelle commented 1 year ago

Content is on vNext and will publish with 23.0.0.9. Closing as completed.

OpenLiberty / docs