Merge branch 'main' of https://github.com/oracle/weblogic-deploy-tooling

Author: rjeberhard

documentation/1.9/content/KnownIssues.md

@@ -1,4 +1,4 @@
-## Known Issues for Oracle WebLogic Server Deploy Tooling
+## Known Issues for WebLogic Deploy Tooling
 
 The following list contains known issues. Each issue may contain a workaround or an associated issue number.
 

documentation/1.9/content/_index.md

@@ -3,44 +3,26 @@
 Many organizations are using WebLogic Server, with or without other Oracle Fusion Middleware components, to run their enterprise applications.  As more and more organizations move toward Continuous Delivery of their applications, the importance of automated testing grows.  Automating WebLogic Server domain creation and application deployment with hand-coded WLST scripts is challenging.  After those scripts exist for a project, they must be maintained as the project evolves.  WebLogic Deploy Tooling (WDT) removes the need for most users to write WLST scripts for routine domain creation and application deployment tasks.  Instead, you can write a declarative, metadata model describing the domain and applications (with their dependent resources), and use one or more of the single-purpose tools that perform domain lifecycle operations based on the content of the model.  This makes it easy to stand up environments and perform domain lifecycle operations in a repeatable fashion based on a metadata model that can be treated as source and evolve as the project evolves.
 
 
-WDT provides several single-purpose tools, all exposed as shell scripts (for both Windows and UNIX):
+WDT provides several single-purpose tools, all exposed as shell scripts (for both Windows and UNIX). For detailed information, see [WDT Tools]({{< relref "/userguide/tools/" >}}).
 
-- The [Create Domain Tool]({{< relref "/create.md" >}}) (`createDomain`) understands how to create a domain and populate the domain with all resources and applications specified in the model.
-- The [Update Domain Tool]({{< relref "/update.md" >}}) (`updateDomain`) understands how to update an existing domain and populate the domain with all resources and applications specified in the model, either in offline or online mode.
-- The [Deploy Applications Tool]({{< relref "/deploy.md" >}}) (`deployApps`) understands how to add resources and applications to an existing domain, either in offline or online mode.
-- The [Discover Domain Tool]({{< relref "/discover.md" >}}) (`discoverDomain`) introspects an existing domain and creates a model file describing the domain and an archive file of the binaries deployed to the domain.
-- The [Encrypt Model Tool]({{< relref "/encrypt.md" >}}) (`encryptModel`) encrypts the passwords in a model (or its variable file) using a user-provided passphrase.
-- The [Validate Model Tool]({{< relref "/validate.md" >}}) (`validateModel`) provides both standalone validation of a model as well as model usage information to help users write or edit their models.
-- The [Compare Model Tool]({{< relref "/compare.md" >}}) (`compareModel`) compares two model files.
-- The [Prepare Model Tool]({{< relref "/prepare.md" >}}) (`prepareModel`) prepares model files for deploying to WebLogic Server Kubernetes Operator environment.
-- The [Extract Domain Resource Tool]({{< relref "/kubernetes.md" >}}) (`extractDomainResource`) generates a domain resource YAML for use with the Oracle WebLogic Server Kubernetes Operator.
-- The [Variable Injector Tool]({{< relref "/variable_injection.md" >}}) is used to tokenize a model with variables.
-- The [Model Help Tool]({{< relref "/model_help.md" >}}) (`modelHelp.sh`) provides information about the folders and attributes that are valid for sections and folders of a domain model.
 
-As new use cases are discovered, new tools will likely be added to cover those operations but all will use the metadata model to describe what needs to be done.
+### Current production release
 
+The current [release](https://github.com/oracle/weblogic-deploy-tooling/releases) of WebLogic Deploy Tooling is 1.9.11. This release was published on March, 2021.
 
-### Download and Install the Software
+### Recent changes and known issues
 
-The Oracle WebLogic Server Deploy Tooling project repository is located at [`https://github.com/oracle/weblogic-deploy-tooling`](https://github.com/oracle/weblogic-deploy-tooling).  Binary distributions of the `weblogic-deploy.zip` installer can be downloaded from the [GitHub Releases page](https://github.com/oracle/weblogic-deploy-tooling/releases).  To install the software, simply unzip the `weblogic-deploy.zip` installer on a machine that has the desired versions of WebLogic Server installed.  After being unzipped, the software is ready to use, just set the `JAVA_HOME` environment variable to point to a Java 7 or higher JDK  and the shell scripts are ready to run.
+See the [Release Notes]({{< relref "/release-notes.md" >}}) for recent changes, known issues, and workarounds.
 
+### About this documentation
 
-### Supported WLS Versions
+This documentation includes sections targeted to different audiences. To help you find what you are looking for more easily, please consult this table of contents:
 
-For the supported WebLogic Server and JDK versions required to run WebLogic Server Deploy Tooling, see [Supported WLS Versions]({{< relref "/wls_versions.md" >}}).
+* [Concepts]({{< relref "/concepts/" >}}) explains the underlying metadata model, files, and configurations...
+* The [User guide]({{< relref "/userguide/" >}}) contains detailed usage information, including how to install and configure WebLogic Deploy Tooling, and how to use each tool.
+* The [Samples]({{< relref "/samples/" >}}) provide detailed example code and instructions that show you how to perform various tasks.
+* The [Developer guide]({{< relref "/developer/" >}}) provides details for people who want to understand how WDT is built, tested, and so on.
 
 
-## Concepts
-
-- [The Model]({{< relref "/model.md" >}})
-- [The Archive File]({{< relref "/archive.md" >}})
-- [Model Use Cases]({{< relref "/use_cases.md" >}})
-- [Tools Configuration]({{< relref "/tool_configuration.md" >}})
-
-## Developer Guide
-
-For information for developers, see the [Developer Guide]({{< relref "/developer/_index.md" >}}).
-
-## Known Issues
-
-See the following list of [Known Issues]({{< relref "/KnownIssues.md" >}}) and workarounds.
+### Contributing
+Those who wish to contribute to the WebLogic Deploy Tooling code will find useful information [here](https://github.com/oracle/weblogic-deploy-tooling/blob/master/CONTRIBUTING.md).

documentation/1.9/content/concepts/_index.md

@@ -0,0 +1,9 @@
++++
+title = "Concepts"
+date = 2019-02-22T15:27:54-05:00
+weight = 1
+chapter = true
+pre = "<b>1. </b>"
++++
+
+# Concepts

documentation/1.9/content/archive.md renamed to documentation/1.9/content/concepts/archive.md

@@ -1,14 +1,22 @@
-# The Archive File
+---
+title: "Archive File"
+date: 2019-02-23T17:19:24-05:00
+draft: false
+weight: 2
+---
+
 
 The archive file is used to deploy binaries and other file resources to the target domain. The archive is a ZIP file with a specific directory structure.  Any file resources referenced in the model that are not already on the target system must be stored in the correct location in the archive, and the model must reflect the path into the archive. The model itself can also be stored inside the archive, if desired.
 
 Note that file resources that already exist on the target system need not be included in the archive, provided that the model specifies the correct location on the target system.
 
+### Contents
+
 - [Example](#example)
 - [Archive Structure](#archive-structure)
 - [Using Multiple Archive Files](#using-multiple-archive-files)
 
-## Example
+#### Example
 
 This example shows an application with a `SourcePath` value referencing an EAR file resource contained in the archive.
 
@@ -23,22 +31,22 @@ appDeployments:
 
 The example above shows the attribute `SourcePath` of the `simpleear` application with a value of `wlsdeploy/applications/simpleear.ear`.  The prefix `wlsdeploy/` indicates that the resource is located in the archive file in the specified location, and will be deployed to that directory in the domain, in this case `<domain-home>/wlsdeploy/applications/simpleear.ear`.
 
-## Archive Structure
+### Archive Structure
 
 These are the paths within the archive that are used for different types of resources. Users can create further directory structures underneath these locations to organize the files and directories as they see fit.  
 
-### `atpwallet`
+#### `atpwallet`
 
 The directory where a wallet can be stored for use with Oracle Autonomous Transaction Processing Cloud Database. The file resource name is not specified in the model, and is assumed to be a single ZIP file in the archive at this location.  
 
-### `model`
+#### `model`
 The directory where the model is optionally located. Only one model file, either in YAML or JSON, is allowed, and it must have the appropriate YAML or JSON file extension.
 
-### `opsswallet`
+#### `opsswallet`
 
 The directory where a wallet can be stored for use with Oracle Platform Security Services. The file resource name is not specified in the model, and is assumed to be a single ZIP file in the archive at this location.  
 
-### `wlsdeploy/applications`
+#### `wlsdeploy/applications`
 The root directory under which applications are stored. Applications can be stored in the archive as EAR or WAR files, or expanded* under this folder. A sample expanded WAR application might have these entries:
 ```
 wlsdeploy/applications/myApp/index.jsp
@@ -50,41 +58,41 @@ wlsdeploy/applications/myApp/WEB-INF/weblogic.xml
 
 \* Expanded application directories are supported after WebLogic Deploy Tooling release 1.6.2
 
-### `wlsdeploy/classpathLibraries`
-The root directory under which JARs/directories used for server classpaths are stored. Every file resource under this directory is extracted, even those not referenced in the model. 
+#### `wlsdeploy/classpathLibraries`
+The root directory under which JARs/directories used for server classpaths are stored. Every file resource under this directory is extracted, even those not referenced in the model.
 
-### `wlsdeploy/coherence`
+#### `wlsdeploy/coherence`
 The root directory under which empty directories must exist for Coherence persistent stores.
 
-### `wlsdeploy/domainBin`
+#### `wlsdeploy/domainBin`
 The root directory under which $DOMAIN_HOME/bin scripts are stored. Only scripts referenced in the `domainInfo/domainBin` section of the model are extracted.
 
-### `wlsdeploy/domainLibraries`
+#### `wlsdeploy/domainLibraries`
 The root directory under which `$DOMAIN_HOME/lib` libraries are stored. Only libraries referenced in the `domainInfo/domainLibraries` section of the model are extracted.
 
-### `wlsdeploy/nodeManager`
+#### `wlsdeploy/nodeManager`
 The root directory under which node manager file resources, such as keystore files, are stored.
 
-### `wlsdeploy/scripts`
+#### `wlsdeploy/scripts`
 The root directory under which scripts are stored. These can include JDBC create scripts, and WLDF action scripts.
 
-### `wlsdeploy/servers`
+#### `wlsdeploy/servers`
 The root directory under which server files, such as keystore files, are stored. These are organized by server name, such as `wlsdeploy/server/my-server/mykey.jks`
 
-### `wlsdeploy/sharedLibraries`
+#### `wlsdeploy/sharedLibraries`
 The root directory under which shared libraries are stored. These are stored as JAR files within the archive.
 
-### `wlsdeploy/stores`
+#### `wlsdeploy/stores`
 The root directory under which empty directories must exist for `FileStore` elements in the model.
 
-## Using Multiple Archive Files
+### Using Multiple Archive Files
 
 The Create Domain, Update Domain, Deploy Applications, and Validate Model Tools allow the specification of multiple archive files on the command line. For example:
 
     weblogic-deploy\bin\createDomain.cmd -archive_file one.zip,two.zip,three.zip ...
 
 File resources can be present in any of these archives. Resources in each archive will supersede resources found in previous archives.
- 
+
 When the model references a resource that is present in multiple archives, the latest in the list takes precedence. For example, if the model references `wlsdeploy/applications/myapp.ear`, and that resource is present in archives `one.zip` and `two.zip`, the resource in `two.zip` will be used.
 
 A similar rule applies for resources that have an assumed location, but are not specifically called out in the model. For example, if archive `two.zip` has a wallet in location `atpwallet/wallet2.zip`, and `three.zip` has a wallet in location `atpwallet/wallet3.zip`, the wallet `atpwallet/wallet3.zip` will be used.

documentation/1.9/content/model.md renamed to documentation/1.9/content/concepts/model.md

@@ -1,4 +1,10 @@
-## The Metadata Model
+---
+title: "Metadata Model"
+date: 2019-02-23T17:19:24-05:00
+draft: false
+weight: 1
+---
+
 
 The metadata model (or model, for short) is a version-independent description of a WebLogic Server domain configuration.  The tools are designed to support a sparse model so that the model need only describe what is required for the specific operation without describing other artifacts.  For example, to deploy an application that depends on a JDBC data source into an existing domain that may contain other applications or data sources, the model needs to describe only the application and the data source in question.  If the data source was previously created, the `deployApps` tool will not try to recreate it but may update part of that data source's configuration if the model description is different than the existing values.  If the application was previously deployed, the `deployApps` tool will compare the binaries to determine if the application needs to be redeployed or not.
 
@@ -25,7 +31,7 @@ The model is written in YAML (or optionally, JSON).  The YAML parser, built into
 
 All assignment statements must have one or more spaces between the colon and the value.  All comments must have a space after the pound sign (also known as hash) to be considered a comment.  YAML doesn't allow comments in all locations.  While the YAML parser used by the framework does not try to enforce these restrictions, it is likely that putting comments in some locations may cause parse errors since YAML is a difficult language to parse due to its complex indention rules.
 
-## Contents
+### Contents
 
 - [Top-Level Sections](#top-level-model-sections)
 - [Simple Example](#simple-example)
@@ -44,7 +50,7 @@ The tooling has five top-level model sections:
 - `appDeployments` - The location where shared libraries and applications are specified.
 - `kubernetes`     - The location where the WLS Kubernetes Operator domain configuration is specified.
 
-### Simple Example
+#### Simple Example
 Here is a simple example of a model to deploy an application and its data source:
 
 ```yaml
@@ -83,7 +89,7 @@ The above example shows two important features of the framework.  First, notice
 
 Second, notice that the `jsf#2.0` shared library `SourcePath` attribute value starts with `@@WL_HOME@@`. This is a path token that can be used to specify that the location is relative to the location of the WebLogic Server home directory on the target environment.  See [Model Tokens](#model-tokens) for more information and a list of available path tokens.
 
-The example above shows the attribute `SourcePath` of the `simpleear` application with a value of `wlsdeploy/applications/simpleear.ear`.  The prefix `wlsdeploy/` indicates that the resource is located in the archive file in the specified location, and will be deployed to that directory within the domain, in this case `<domain-home>/wlsdeploy/applications/simpleear.ear`. See [The Archive File](archive.md) for more details about using the archive file.
+The example above shows the attribute `SourcePath` of the `simpleear` application with a value of `wlsdeploy/applications/simpleear.ear`.  The prefix `wlsdeploy/` indicates that the resource is located in the archive file in the specified location, and will be deployed to that directory within the domain, in this case `<domain-home>/wlsdeploy/applications/simpleear.ear`. See [The Archive File]({{< relref "/concepts/archive.md" >}}) for more details about using the archive file.
 
 Users can create further directory structures underneath the above locations to organize the files and directories as they see fit.  Note that any binary that already exists on the target system need not be included in the archive provided that the model specified the correct location on the target system.
 
@@ -248,7 +254,7 @@ This feature can also remove items that were created by WebLogic Server template
                 ...
 ```
 
-This feature does not apply to named security providers within a realm. These items follow a special set of rules that are required to maintain their ordering. See [Modeling Security Providers](use_cases.md#modeling-security-providers) for detailed information.
+This feature does not apply to named security providers within a realm. These items follow a special set of rules that are required to maintain their ordering. See [Modeling Security Providers]({{< relref "/concepts/use_cases#modeling-security-providers" >}}) for detailed information.
 
 This feature cannot be use to un-deploy applications or remove libraries.