Packaging and deploying applications

[Charlotte-Holt]

Red Hat built the 'Packaging and deploying applications' guide on 10/16/2019. The PDF and HTML versions are attached here:

• GettingStarted_RHRBuild_10:16:2019.zip

• GettingStarted_RHRBuild_10:16:2019.pdf

We need to determine if there's a better way to display pom.xml, server.xml, SystemReadinessCheck.java, and SystemLivenessCheck.java. Right now, they're included in the middle of the text, and some of them are included multiple times. We could try including them at the end of the guide in some sort of appendix. Then, each reference to one of these files/classes could link down to the appropriate file in the appendix section of the guide. This is assuming that the instances of each file are all the same. Restructuring the guides into this appendix/linking format could be a good starting point for usability testing to determine whether the linking would involve too much movement up and down the page.

It also appears the legal notice needs to be updated, but that may have already been addressed indirectly when we updated the legal notice for the docs.

[Charlotte-Holt]

We will no longer be building the guide into RHR docs. Instead, we'll create a new concept topic that covers the key concepts from the getting-started guide.

[lauracowen]

Looks great, thank you. I've pasted into Graham to ask him to take a look but otherwise, these are the only things that stood out to me:

• "and download specific feature versions that are listed as dependencies." Is it worth adding that this means that only the features required are included in the package? Maybe double-check with SME that that's true but I think it is.
• Gradle section has a typo: "it's" when you mean "its".
• could maybe link "Dockerfile" to whatever Docker docs explain the concept of a Dockerfile? It's good for SEO to link to external websites as well as our own.
• Containerize section - don't link to the "Using Docker containers to developer ms" here because that guide is for using Docker in development context. Just the "Containerizing ms" one is relevant here.
• Just to annoy, I've requested that we rename the "Packaging and deploying apps" guide to "Getting started with Open Liberty" guide, as that's more appropriate description. It doesn't matter to this topic other than you need to know to give the right name in the link text. :)

Our H2 and H3 headings are almost indistinguishable...maybe mention it to Melissa?

Assuming Graham doesn't come back with anything significant, and you can make the changes above, I'd be happy for this to be published and even in RHR if it's not too late? Otherwise, it gives us something new for RHR next month :)

[lauracowen]

There's a dodgy inclusion statement after the maven/gradle config examples. It's not resolved into whatever it should display.

Aside from that, I'm happy with this. I'll sign it off so you can just fix the inclusion statement while others can start reviewing it. Thanks

[lauracowen]

https://draft-openlibertyio.mybluemix.net/docs/ref/general/#packaging-deploying.html

[NottyCode]

Rather than intro maven with this:

With Maven, you use a Project Object Model (POM) file written in XML...

what about saying this:

With Maven, you use a pom.xml file...

I generally hear people talking about pom files, I don't know how aware people are (or need to be) that pom stands for Project Object Model.

I'm wondering if we need to say this:

While Maven build scripts are written in XML, Gradle build scripts are made up of incremental tasks that form a program.

It implies to me that maven is primary and Gradle should be thought of in terms of Maven. What about writing an intro paragraph that talks about what the tools are used for and their common role, then talk about the independent parts. Something like this:

Maven and Gradle are build automation tool that makes managing your builds and dependencies easier. The Open Liberty project provides Maven and Gradle plugins to help you develop and package applications with Open Liberty.

Even if you are deploying to the cloud you deploy the application to Liberty as a war file:

If you don’t plan on containerizing your application for the cloud, you can configure Open Liberty to run the application from a WAR file.

I don't know why the doc says you must change the port number, you do not need to:

...you must change the default HTTP port of the server to the port where the application will be accessed by replacing the httpPort attribute value in the server.xml file.

You do typically need to set the host name, was that meant?

We don't do what is advised in 'Packaging for containerization' in any of our common deployment practices. That makes me uneasy about this section. Can we get maven/gradle tabs like elsewhere in the site?

I wouldn't use installation in this sentence:

The runnable option is used to package an application and an Open Liberty installation into a runnable JAR file.

There seems to be an adoc include error:

Unresolved directive in packaging-deploying.adoc - include::{common-includes}/maven-gradle-tabs.adoc[]

also:

Unresolved directive in packaging-deploying.adoc - include::{common-includes}/maven-gradle-tabs.adoc[]

Is this section necessary:

Deploying WAR files on an Open Liberty server

[lauracowen]

I think this is still trying to be a task (from "Building a WAR deployment artifact" onwards) but wouldn't be that successful as a task because it's not providing the detail that you'd get from the relevant guides. The Getting Started guide handles that at a basic level, then the containerising guide handles it more in-depth (I think), and the Maven and Gradle guides handle the details of the build tools. So think this should stay away from procedural and focus on explaining value/approaches, and why you'd do stuff.

I think remove the WAR section. The two main options that are described in the intro are containerised packages for cloud (K8s/OpenShift, in this case), and server packages for trad environments.

Containerization section

Contrary to Graham's suggestion, I think the Containerization section should come first as that's more relevant. As you're not instructing how to do it, it doesn't really matter if creating WARs is the pre-req. Just describe why you'd create a containerised package and what it is.

There are Open Liberty Docker images hosted on DockerHub and built on UBI and using Java 11 (probably don't need to mention the Java version but I mention it here because that's why I've given the UBI Docker image link instead of the Docker Official Images link. However, it may be appropriate to introduce both? The "official" images are built on Ubuntu but they currently don't go as far as Java 11 so maybe we shouldn't mention them for now at least. Also, they're both "official" as far as we're concerned - we upload them both - so I don't think UBI should be made to appear "unofficial".

Anyway, my point is that you could introduce the Docker images that we supply as Open Liberty and that they can be used as the basis of your own Dockerfile, which would create a Docker image based on one of the Open Liberty images and then copy your application into the container when it starts. The application it copies in is a WAR file (a compressed archive file that contains xxxx) which has been built by Maven/Gradle tools. You could even show an example Dockerfile from the Getting Started guide either in the topic or just as a link (it's short enough it might be useful to just include it in the topic - could literally use an include statement rather than copying it).

I don't think you need to show the POM or build.gradle (though you could link to example Maven POM in the GS guide repo, if you think it's useful?). Could link from here to the Getting Started guide section for a simple walkthrough of doing it, and/or to the containerizing guide for a more in-depth one (I assume).

Can then host the container image on a repo such as DockerHub or similar and use that in a pipeline to deploy it to OpenShift etc (might be best checking the containerizing guide that I've not skipped a massive step there, but I think that's the basic idea).

So, I don't think you need the detail that's above the maven/gradle examples, or really the maven/gradle examples.I don't think you need the first para after the gradle example.

The last two paras in that section are useful but could be collapsed together to touch on dockerfile and layers. Regarding multi-layered, could say that if you put the OL installation/binaries in an earlier layer of the dockerfile (eg by using the docker image in DockerHub, then adding later lines in the dockerfile that run featureUtility installFeatures to install the features you need, then copy in your app and its server config), when the container is rebuilt, unless there's a change in the OL version (say), that layer won't get rebuilt. And unless you change the features listed in the dockerfile, the features won't get installed again. So only your app/config layer will get rebuilt (if it's changed), which is better performance etc.

NB I checked with Alasdair about featureUtiltiy installServerFeatures and he agreed with my definition of it that I gave to you and David today. However, there's a performance downside because if you run installServerFeatures, you have to have the app and its server config in an earlier layer than the feature installation. Which means that whenever you change the app/config, you have to do the feature installation bit again. Which is potentially a performance hit (if a lot of features). So not great practice. But using installFeatures requires you to manually list out the features in the dockerfile as well as in server.xml and poss the pom.xml (?), so not so efficient either. Not really a good answer at the moment, though maybe we could copy over the server.xml then run installServerFeatures, then copy the app and server config across as the last layer. I think for now just link to installFeatures, then get Alasdair to review it.

Server package section

So then, I think we've done the most relevant bit and now we can cover the alternative approach for if you've got a more trad setup. First para is fine.

Server packages for deploying to an Open Liberty server sub-section (needs a better heading than that though!)

This is basically the war/zip/tar/tar.gz bit. Not sure exactly how to position the different formats but we basically talk about WAR files mainly (which are a zip file with metadata). Maybe just focus on WAR and say that you can use other archive formats if you prefer (but I don't know why you would). (also, I checked with Alasdair and he talked Graham out of tar.gz so don't talk about that afterall)

You build the WAR file which contains your app and its server config, then deploy that WAR file on to a server you've created/started in your Open Liberty installation (I think the app starts automatically when you do that but you can start/stop the app manually, as well as start/stop the server+app manually; bascially you can do the things that the server command supports). If you change the app/config, you have to rebuild the WAR file and redeploy it to the server.

When you build the WAR file, I think that all the features that are installed in your OL installation are included in the WAR file, unless you also run minify which strips out anything not listed in the server.xml.

** Runnable JAR files (also known as uberjar or fatjar) sub-section**
The JAR option is a little different from the other types of archive because the output (a .jar file) is a standalone runnable thing (as long as you have Java installed). You just run it from the cmdline (don't have to separately install OL on the production server). It's basically the equivalent of what Spring do with uberjars (though don't mention Spring by name) because everything is in there and you don't need to worry about installing and starting a server etc. And you can make your uberjars thinner by running minify (so it doesn't just include every feature that was part of the OL installation and, instead, packages only the features that are used by the app - I think it scans the server.xml).

However, while runnable JARs (or fatjars) are useful for easy deployment on traditional environments, they're less useful for containerizing because every time the container is rebuilt, the layers of the container that contain both Open Liberty and your application have to be rebuilt. If you use WAR files when containerizing (which don't contain the Open Liberty installation), only the application layer (ie your application) has to be rebuilt when the container is rebuilt (as shown in the Dockerfile example above where it pulls the Open Liberty part of the container from a pre-built image in DockerHub).

(This last bit about disadvantages of JAR files is not directly relevant to trad environments but it's a strength of WAR format over JAR, and I think could be included here emphasise that, esp in the context of people moving towards containerizing apps. Alasdair agreed with including it.)

And obvs links out to all the relevant server and featureUtiltiy commands and guides in each section.

Minor wording thing in the intro:

• "server packages that are appropriate for..." -> "server packages which are more appropriate for..." ? (I read it as a continuation of "containerization" initially and then wondered why containerization was good for trad setups...

[Charlotte-Holt]

@lauracowen Thanks for all the feedback. Very helpful! I think I got it all in this draft (I tried to, at least). Points to mention:

• I used some of your wording in some places (changed around a bit), so I hope that's okay :)
• I didn't mention the images built on Ubuntu. It seemed like we weren't sure on this, so I just mentioned the UBI ones and left the Ubuntu ones out for now
• My include statement for the Dockerfile isn't currently working, but I'm actively trying to resolve that now. I'll let you know when done.
• The link to the featureUtility command will have to change since I'm breaking out those topics, but for now I just linked to the existing doc.

[lauracowen]

• Yes, unless we get Ubuntu images with newer Java versions, stick with just the UBI one for now.
• Probably don't need the ", which are appropriate for more traditional setups." bit as you explain the difference in the next sentences. Also, I keep reading this sentence wrong as it's currently punctuated ("...formats for containerization and server packages") so simplifying it might be better anyway. :)
• I don't understand what "a domain-specific language" means here (what's the domain in this case? are there multiple different languages you can use with Gradle config?), but I don't know much about Gradle either.
• "a web.xml file that tells Open Liberty" -> "...which tells..."?
• "If your Open Liberty installation is in an earlier layer " I'd maybe change to "As long as your Open Liberty installation is in an earlier layer " and maybe put the "unless" part as a separate sentence. Otherwise, the sentence is a bit windy with two conditional statements in it ("if" then "unless"). See what you think.
• (check with technical reviewer but...) "Open Liberty supports zip, jar, tar, and tar.gz package types." should maybe be followed by something like "A WAR file is typically/most commonly used." which then gives a sense of why you only talk about WAR file after that. I'm not actually sure why/when you'd use the other file formats and it may not even be worth mentioning them? (again, check this with @NottyCode or whoever reviews).
• I think there's slightly weird line spacing in the RUnnable JAR files section. I think it might be because the monospace font takes up more vertical space, so the first two paras are more widely line-spaced than the third which doesn't have any monospace in it. Could you raise an issue for Melissa or the website team to check?
• I think the server package intro needs to re-state the contrast to the containerizing section. Something about "An alternative to containerizing applications by including the WAR file in the container (or something!) is to deploy the WAR file directly to an OL installation. A WAR file is a server package..". Then also, at the end of the Runnable JAR section it talks about why it's not good for containerization (even though this isn't the section about containers), which is fine, I think it should say this, but I think maybe the server packages for deployment section should also refer back to the containerization section to clarify it's relationship (ie can be deployed directly or can be containerized). I think this is why Graham wanted the server package section to go first - if that's the only way to make it make sense, I can live with that. However, I would rather lead with containerization as you don't need to understand the details of a WAR file to get the container scenario and that's the scenario we'd rather they took now. To be honest, I may be being picky in trying to tie everything up together - and what you have is pretty good as far as I'm concerned and i'm happy to sign it off but see what you think and check the technical reviewer perspective too.

[Charlotte-Holt]

@lauracowen Thx for the feedback! Comments here:

• Probably don't need the ", which are appropriate for more traditional setups." bit as you explain the difference in the next sentences. Also, I keep reading this sentence wrong as it's currently punctuated ("...formats for containerization and server packages") so simplifying it might be better anyway. :)
• I don't understand what "a domain-specific language" means here (what's the domain in this case? are there multiple different languages you can use with Gradle config?), but I don't know much about Gradle either. It means that the language that the config is written in is specific to Gradle, from what I understand :) Found this: https://docs.gradle.org/current/dsl/index.html
• "a web.xml file that tells Open Liberty" -> "...which tells..."?
• "If your Open Liberty installation is in an earlier layer " I'd maybe change to "As long as your Open Liberty installation is in an earlier layer " and maybe put the "unless" part as a separate sentence. Otherwise, the sentence is a bit windy with two conditional statements in it ("if" then "unless"). See what you think.
• (check with technical reviewer but...) "Open Liberty supports zip, jar, tar, and tar.gz package types." should maybe be followed by something like "A WAR file is typically/most commonly used." which then gives a sense of why you only talk about WAR file after that. I'm not actually sure why/when you'd use the other file formats and it may not even be worth mentioning them? (again, check this with @NottyCode or whoever reviews). - Checking with @NottyCode on this
• I think there's slightly weird line spacing in the RUnnable JAR files section. I think it might be because the monospace font takes up more vertical space, so the first two paras are more widely line-spaced than the third which doesn't have any monospace in it. Could you raise an issue for Melissa or the website team to check? Checking with Steven on this - I think it might be fixed by Antora
• I think the server package intro needs to re-state the contrast to the containerizing section. Something about "An alternative to containerizing applications by including the WAR file in the container (or something!) is to deploy the WAR file directly to an OL installation. A WAR file is a server package..". Then also, at the end of the Runnable JAR section it talks about why it's not good for containerization (even though this isn't the section about containers), which is fine, I think it should say this, but I think maybe the server packages for deployment section should also refer back to the containerization section to clarify its relationship (ie can be deployed directly or can be containerized). I think this is why Graham wanted the server package section to go first - if that's the only way to make it make sense, I can live with that. However, I would rather lead with containerization as you don't need to understand the details of a WAR file to get the container scenario and that's the scenario we'd rather they took now. To be honest, I may be being picky in trying to tie everything up together - and what you have is pretty good as far as I'm concerned and i'm happy to sign it off but see what you think and check the technical reviewer perspective too.

[Charlotte-Holt]

@NottyCode Please read through this topic and provide feedback: https://draft-openlibertyio.mybluemix.net/docs/ref/general/#application-packaging.html. Also, could you address Laura's question above:

Open Liberty supports zip, jar, tar, and tar.gz package types." should maybe be followed by something like "A WAR file is typically/most commonly used." which then gives a sense of why you only talk about WAR file after that. I'm not actually sure why/when you'd use the other file formats and it may not even be worth mentioning them?

[NottyCode]

A war is an application packaging type and zip, jar, tar and tar.gz are server packaging types. So I don't think the suggested follow on makes sense, they are talking about different things. Although the fact that Laura asks suggests that it isn't right yet.

[lauracowen]

@NottyCode ok - when would you use each then? why would you only package the server?

[NottyCode]

@lauracowen if you package a server it packages the application as a part of it.