Merge branch 'draft' into vNext

.github/ISSUE_TEMPLATE/feature-issue-template.md

@@ -0,0 +1,34 @@
+---
+name: Open an feature issue
+about: Development or doc teams only- open an issue to satisfy documentation requirements for an Open Liberty feature epic
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Use this template for updates associated with Open Liberty development epics. Title the issue Documentation:<Development epic name> and provide the following information**
+
+
+**Link to development epic**:
+**Target GA release**:
+
+**Provide a concise summary of your feature. What do 80% of target users need to know to be most easily productive using your runtime update?**
+
+
+
+
+**List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:**
+
+
+
+
+**To udpate existing topics, specify a link to the topics that are affected.  Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ**
+
+
+
+
+
+
+
+**To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.**

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "asciidoc.antora.enableAntoraSupport": true
+}

antora.yml

@@ -1,6 +1,6 @@
 name: docs # Do not rename since it will mess up the path in the url
 title: Docs overview
-version: 23.0.0.11
+version: 23.0.0.12
 start_page: ROOT:overview.adoc
 asciidoc:
   attributes:

modules/ROOT/nav.adoc

@@ -4,9 +4,9 @@
 // Begin basics section
 .Basics
 * xref:zero-migration-architecture.adoc[Zero migration]
-* xref:development-mode.adoc[Dev mode]
+* xref:dev-mode.adoc[Dev mode]
 * xref:java-se.adoc[Java SE support]
-* xref:installing-open-liberty-betas.adoc[Installing Open Liberty beta releases]
+* xref:installing-open-liberty-betas.adoc[Install Open Liberty beta releases]
 * xref:develop-liberty-tools.adoc[Develop with Liberty Tools]
 * https://openliberty.io/guides/getting-started.html[Guide: Getting started with Open Liberty]
 
@@ -18,8 +18,8 @@
 * xref:container-images.adoc[Container images]
   ** xref:verify-signatures-for-container-images-in-open-liberty.adoc[Verify signatures for container images in Open Liberty]
 * xref:rest-microservices.adoc[RESTful services]
-  ** xref:sync-async-rest-clients.adoc[Sync and async REST clients]
   ** xref:rest-clients.adoc[REST clients]
+  ** xref:sync-async-rest-clients.adoc[Sync and async REST clients]
   ** xref:json-p-b.adoc[JSON-P and JSON-B]
   ** xref:send-receive-multipart-jaxrs.adoc[Send and receive multipart/form-data parts]
   ** https://openliberty.io/guides/#restful_service[Guides: RESTful services]
@@ -105,6 +105,7 @@
 * xref:class-loader-library-config.adoc[Class loader configuration]
 * xref:virtual-hosts.adoc[Virtual hosts]
 * xref:application-bindings.adoc[Application bindings]
+* xref:loose-applications.adoc[Loose applications]
 * https://openliberty.io/guides/#kubernetes[Guides: Kubernetes]
 * https://openliberty.io/guides/#cloud_deployment[Guides: Cloud deployment]
 

modules/ROOT/pages/JSON-log-format.adoc

@@ -0,0 +1,46 @@
+// Copyright (c) 2020 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:
+:seo-title:
+:page-layout: general-reference
+:page-type: general
+= JSON log format
+
+Logs provide valuable insights into the performance of your applications, but they can be difficult to parse and understand without special log analysis tools. JSON is a standard log data format that is used by many popular log analysis tools and platforms, such as the Elastic Stack and Splunk.
+
+JSON is a structured data format that is compact and human-readable. It is also standardized, which means that log analysis tools can parse it efficiently, regardless of the application.
+When you configure your logs to output in JSON format, you can aggregate, manage, and analyze them with any platform or service that reads JSON. Log analysis platforms can help you get a comprehensive view of what's going on in your application, as well as troubleshoot particular issues your users are experiencing. You can even add your own custom JSON fields to the logs to gather data about a particular user or session.
+
+== Configure Open Liberty logs in JSON format
+
+There are three different options to configure your logs in JSON format:
+
+- the `bootstrap.properties` file
+- environmental variables
+- the `server.xml` file
+
+Which option is best for you depends on the details of your applications and server configuration. For more information, see xref:log-trace-configuration.adoc#_json_logging[the JSON logging section of Log and trace configuration].
+
+=== Change default field names
+
+In some cases, you might want to change the default field names in your Open Liberty logs to match the field names from other containers in the configuration. For example, an Open Liberty message is referred to by the field name `message`, while another container’s message might be referred to by a field called `log`. In this case, two different visualizations of the messages would show in the logs on a dashboard. However, if you modify the Open Liberty output field names to  match the field names from the other container, the fields can all be viewed in the same visualization. For more information, see xref:log-trace-configuration.adoc#_configuring_json_field_names[the Configuring JSON field names section of Log and trace configuration].
+
+=== Add custom fields
+
+You can also add custom fields to your JSON log output so you can better understand certain aspects of your application performance. For example, if you want to check all the requests that originated from a particular user, you can add a custom field to the logs for that user's ID. Furthermore, you can add another field for session ID, so that you can diagnose issues with a specific session that is associated with the user. Any dashboards that you build from this logging configuration can display these custom fields. For more information, see **link pending**.
+
+=== Make your logs more human-readable
+
+Although JSON is considered a human-readable format, JSON logs output to a single line and can be difficult to read at a glance. link:https://stedolan.github.io/jq/[jq] is an open source  command-line JSON processor that you can use to output your JSON logs in a more human-readable format. With jq, you can parse your logs so that each field is on its own line. You can also customize your query to include only certain logs or fields within a log in the output. For more information, see https://stedolan.github.io/jq/manual/[the jq documentation].
+
+== See also
+
+- For an overview of JSON logging configuration in Open Liberty, check out link:https://developer.ibm.com/technologies/java/videos/use-json-logging-in-open-liberty/[this video from IBM Developer].
+- To learn more about log management solutions for Open Liberty, see xref:log-management.adoc[Log management].
+- To learn about Open Liberty logs and logging configuration options, see xref:log-and-trace-configuration.adoc[Log and trace configuration].

modules/ROOT/pages/admin-center.adoc

@@ -67,6 +67,8 @@ For example, if your browser is running on the same computer as your server and
 
 `https://localhost:9443/adminCenter`
 
+Access to Admin Center is supported only when the access comes directly from a browser. Access through an HTTP proxy server is not supported.
+
 If your browser prompts you to confirm that the connection is trusted, specify an exception or otherwise enable the connection to continue to Admin Center.
 To log in to Admin Center, specify the username and password from your management role configuration. For example, if you use the previously provided example `server.xml` configuration, specify `admin` as the username and `adminpwd` as the password.
 

modules/ROOT/pages/application-packaging.adoc

@@ -0,0 +1,105 @@
+// Copyright (c) 2020 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
+//
+// This doc is hosted in the Red Hat Runtimes documentation. Any changes made to this doc also need to be made to the version that's located in the PurpleLiberty GitHub repo (https://github.com/PurpleLiberty/docs). 
+//
+:page-description: You can choose among different options for packaging applications with Open Liberty. The simplest workflow for developing your cloud-native applications is to build applications with Maven or Gradle and containerize with Docker, before deploying them to a Kubernetes environment, such as OpenShift.
+:seo-title: Application packaging for deployment - OpenLiberty.io
+:seo-description: You can choose among different options for packaging applications with Open Liberty. The simplest workflow for developing your cloud-native applications is to build applications with Maven or Gradle and containerize with Docker, before deploying them to a Kubernetes environment, such as OpenShift.
+:page-layout: general-reference
+:page-type: general
+= Application packaging for deployment
+
+You can choose among different options for packaging applications with Open Liberty.
+The simplest workflow for developing your cloud-native applications is to build applications with Maven or Gradle and containerize with Docker, before deploying them to a Kubernetes environment, such as OpenShift.
+
+In this context, _packaging_ means bundling together an application with an Open Liberty server into a single deployment artifact.
+You can decide how to package applications based on how you will eventually deploy them.
+
+Open Liberty offers different packaging options, including packaging formats for containerization and server packages.
+If your goal is to deploy an application to a link:https://kubernetes.io/[Kubernetes] environment, <<package-container,package your application for containerization>>.
+If you're working on a more traditional environment, you can create a <<server-package,server package>> that can be used to distribute and deploy an application to any number of machines.
+
+== Maven and Gradle build tools
+Maven and Gradle are build automation tools that make managing your builds and dependencies easier.
+Both build tools help you download dependencies, build source code, run tests, and package applications.
+The Open Liberty project provides Maven and Gradle plug-ins to help you develop and package applications with Open Liberty.
+
+With link:https://maven.apache.org/[Maven], you use a `pom.xml` file to define information about your project.
+To learn more about the Open Liberty Maven plug-in, check out the link:https://github.com/OpenLiberty/ci.maven[Open Liberty Maven plug-in documentation] and this guide on link:/guides/maven-intro.html[Building a web application with Maven].
+
+link:https://gradle.org/[Gradle] uses a build language based on Groovy, and Gradle build scripts are made up of incremental tasks that form a program.
+To learn more about the Open Liberty Gradle plug-in, check out the link:https://github.com/OpenLiberty/ci.gradle[Open Liberty Gradle plug-in documentation] and this guide on link:https://openliberty.io/guides/gradle-intro.html[Building a web application with Gradle].
+
+[#package-container]
+== Packaging for containerization
+A Docker image is a multi-layered file that serves as a template for a Docker container.
+The simplest way to containerize your packaged application is by using the latest Open Liberty Docker images, which include the most recent feature versions and link:/docs/ref/general/#security-vulnerabilities.html[security fixes].
+You can find Open Liberty Docker images hosted on link:https://hub.docker.com/r/openliberty/open-liberty/[Docker Hub].
+
+These images are built on link:https://access.redhat.com/articles/4238681[Universal Base Images (UBI)] and can be used as the foundation for your Dockerfile.
+A Dockerfile is a text file that contains commands about how an image is built.
+You can create a Dockerfile based on an Open Liberty image and then copy your application to the container when it starts.
+The application that's copied is in a WAR file that's built by Maven or Gradle.
+A WAR file is a compressed archive file that contains an application and a `web.xml` file, which tells Open Liberty how to run the application, in addition to other resources that your application needs.
+
+The following example Dockerfile copies a WAR file into a Docker image that contains the Java runtime and an Open Liberty server:
+
+----
+include::https://raw.githubusercontent.com/OpenLiberty/guide-getting-started/master/start/Dockerfile[]
+----
+
+When your application's containerized, you can host the container image on a repository, such as Docker Hub, and use that image in a pipeline for deployment to a Kubernetes environment, like OpenShift.
+If your Open Liberty installation is in an earlier layer of the Dockerfile than your application configuration and you rebuild the container, the Open Liberty layer isn't rebuilt unless there's a change in the Open Liberty installation.
+
+For example, if you use an Open Liberty image from Docker Hub, you might add lines to the Dockerfile that run the link:/docs/ref/general/#featureUtility.html[`featureUtility installFeatures` command] to install features that you need.
+Then, you copy in your application and its server configuration.
+When you rebuild the container, the features aren't installed again unless the features that are listed in the Dockerfile changed.
+Only the layer than contains your updated application and server configuration is rebuilt, which enhances performance by decreasing build times.
+If you plan to run a Docker image in production, make sure to follow link:/docs/ref/general/#server-configuration-hardening.html[server configuration hardening best practices] and link:/docs/ref/general/#application-hardening.html[application configuration hardening best practices].
+
+For a step-by-step guide on updating and deploying an application on Open Liberty with Maven and Docker, see link:https://openliberty.io/guides/getting-started.html[Getting started with Open Liberty].
+To learn more about running applications with Open Liberty Docker images, see this guide on link:/guides/containerize.html[Containerizing microservices].
+
+[#server-package]
+== Server packages
+A server package is a compressed file that can contain an Open Liberty runtime environment, a specific configuration, the applications that are configured into the server, and the files in the shared resources directory, for example, a JDBC driver and configuration.
+You can also choose to exclude the runtime binary files from the compressed file.
+Open Liberty supports `zip`, `jar`, `tar`, and `tar.gz` package types.
+
+=== Server packages for deployment to Open Liberty
+An alternative to containerizing applications by including your WAR file in a container is to deploy the WAR file directly to Open Liberty.
+A WAR file is a server package that contains your application and its server configuration.
+With this packaging option, you can use link:/docs/ref/command/#server-commands.html[server commands] to control the Open Liberty server.
+If you make updates to your application or server configuration, you must rebuild the WAR file and redeploy it to Open Liberty.
+
+Different options can be specified with the `include` parameter or attribute to tailor a server package to meet your needs.
+When you build a WAR file, all features that are installed in your Open Liberty installation are included in the WAR file, unless you specify the `minify` option.
+The `minify` option strips out anything that's not listed in the `server.xml` file and creates a package that contains just enough runtime to support the configured server.
+
+For more information about Open Liberty packaging options with Maven, see the link:https://github.com/OpenLiberty/ci.maven/blob/master/docs/package.md#package[`package` goal in the Maven documentation].
+For more information about Open Liberty packaging options with Gradle, see the link:https://github.com/OpenLiberty/ci.gradle/blob/master/docs/libertyPackage.md#libertypackage-task[`libertyPackage` task in the Gradle documentation].
+
+=== Runnable JAR files
+Another option is to package your application into a link:/docs/ref/general/#runnablejarfiles.html[runnable JAR file].
+The `runnable` option is used to package an application, server, and Open Liberty runtime into a runnable JAR file.
+When you package into a runnable JAR file, you can run your application from the command line without having to separately install Open Liberty on a production server.
+
+The server and application can be started by simply running `java -jar myserver.jar`, where `myserver` is the name of your server.
+The JAR file is portable and ready to deploy both the application and server together.
+The `minify` option can be specified with the `runnable` option to package into a minimum runnable JAR file that contains only what you need to run your application.
+
+While runnable JAR files are useful for easy deployment on traditional environments, they're less useful for containerizing because every time a container is rebuilt, both the Open Liberty and application layers of the container must be rebuilt.
+Alternatively, WAR files don't contain an Open Liberty installation, so only the application layer must be rebuilt when a container is rebuilt.
+
+== See also
+
+* To learn how to update and deploy an application on Open Liberty with Maven and Docker, see this guide about link:https://openliberty.io/guides/getting-started.html[Getting started with Open Liberty].
+* Have a Spring Boot application?
+To learn how to containerize, package, and run a Spring Boot application on an Open Liberty server without modification, see the guide about link:https://openliberty.io/guides/spring-boot.html[Containerizing, packaging, and running a Spring Boot application].
+* To learn the specifics of deploying to different cloud services, including AWS, AKS, and GCP, check out the link:https://openliberty.io/guides/?search=deploy[Open Liberty deployment guides].