WIP: Quick Start Guide

.gitignore

@@ -24,6 +24,8 @@ samples/quickstart/app/target/maven-status
 samples/quickstart/app/target/todo
 # Quickstart local domain directory
 samples/quickstart/todolist_domain
+# Quickstart local domain generated variables file
+samples/quickstart/scripts/local-domain/variables.properties
 # Quickstart developer env file
 samples/quickstart/setQuickstartDevEnv.sh
 samples/quickstart/setQuickstartDevEnv.ps1

documentation/1.5/content/_index.md

@@ -17,22 +17,24 @@ The WKT UI provides a graphical user interface that wraps the WKT tools, Docker,
 a Linux container image to use to run the domain, and setting up and deploying the software and configuration
 necessary to deploy and access the domain in your Kubernetes cluster.
 
+Be sure to check out the [Quick Start]({{< relref "/setup/quickstart/" >}}) guide for a tutorial, which will step you through WebLogic Kubernetes Toolkit UI (WKTUI) functionality and familiarize you with its capabilities.
+
 ### Current release
 
 WebLogic Kubernetes Toolkit UI version and release information can be found [here](https://github.com/oracle/weblogic-toolkit-ui/releases).
 
 ### About the Documentation
 For detailed user information, read the following:
 
-- [About the WKT UI Application]({{< relref "/concepts/_index.md" >}})
+- [About the WKT UI Application]({{< relref "/concepts/" >}})
 - WebLogic Kubernetes Toolkit UI [Prerequisites]({{< relref "/setup/prerequisites.md" >}}) and [Installation]({{< relref "/setup/install.md" >}})
-- [Navigate the WKT UI]({{< relref "/navigate/_index.md" >}})
+- [Navigate the WKT UI]({{< relref "/navigate/" >}})
  - [Model]({{< relref "/navigate/model.md" >}})
  - [Image]({{< relref "/navigate/image.md" >}})
- - [Kubernetes]({{< relref "/navigate/kubernetes/_index.md" >}})
- - [Verrazzano]({{< relref "/navigate/verrazzano/_index.md" >}})
+ - [Kubernetes]({{< relref "/navigate/kubernetes/" >}})
+ - [Verrazzano]({{< relref "/navigate/verrazzano/" >}})
 
-For developer information, see [WebLogic Kubernetes Toolkit UI Project]({{< relref "/developer/_index.md" >}}).
+For developer information, see [WebLogic Kubernetes Toolkit UI Project]({{< relref "/developer/" >}}).
 
 ### Get Help
 

documentation/1.5/content/navigate/_index.md

@@ -7,7 +7,7 @@ pre = "<b> </b>"
 
 ### Before you begin
 
-Make sure you have read [About the WKT UI Application]({{< relref "/concepts/_index.md" >}}).
+Make sure you have read [About the WKT UI Application]({{< relref "/concepts/" >}}).
 
 ### About the UI
 
@@ -21,12 +21,12 @@ The UI sections are:
 - [Project Settings]({{< relref "/navigate/project-settings.md" >}})
 - [Model]({{< relref "/navigate/model.md" >}})
 - [Image]({{< relref "/navigate/image.md" >}})
-- [Kubernetes]({{< relref "/navigate/kubernetes/_index.md" >}})
+- Kubernetes
  - [Client Configuration]({{< relref "/navigate/kubernetes/k8s-client-config.md" >}})
  - [WebLogic Operator]({{< relref "/navigate/kubernetes/k8s-wko.md" >}})
  - [WebLogic Domain]({{< relref "/navigate/kubernetes/k8s-weblogic-domain.md" >}})
  - [Ingress Controller]({{< relref "/navigate/kubernetes/k8s-ingress-controller.md" >}})
-- [Verrazzano]({{< relref "/navigate/verrazzano/_index.md" >}})
+- Verrazzano
  - [Client Configuration]({{< relref "/navigate/verrazzano/vz-client-config.md" >}})
  - [Installation]({{< relref "/navigate/verrazzano/vz-install.md" >}})
  - [Component]({{< relref "/navigate/verrazzano/vz-component.md" >}})

documentation/1.5/content/setup/install.md

@@ -2,13 +2,26 @@
 title: "Install WKT UI"
 date: 2019-02-22T15:44:42-05:00
 draft: false
-weight: 2
+weight: 3
 description: "Install the WKT UI application and check for updates."
 ---
 
 1. Download the latest WebLogic Kubernetes Toolkit UI (WKT UI) application installers from the [GitHub Releases section](https://github.com/oracle/weblogic-toolkit-ui/releases) of this repository.
 2. Simply run the appropriate installer for your operating system.
 
+Each release has many assets, some of which are needed for the application’s auto-update functionality and are not intended to be used for installing the application.
+The following table lists the installer file names and their purpose.
+
+| Installer File Name | Purpose |
+| --- | --- |
+| WebLogic-Kubernetes-Toolkit-UI-1.4.1-arm64.dmg | macOS Apple Silicon (M1) installer. |
+| WebLogic-Kubernetes-Toolkit-UI-1.4.1.AppImage | Linux AppImage package of the application. |
+| WebLogic-Kubernetes-Toolkit-UI-1.4.1.dmg | macOS Intel (x86-64) installer. |
+| WebLogic-Kubernetes-Toolkit-UI-Setup-1.4.1.exe | Windows installer. |
+| wktui-1.4.1.x86_64.rpm | Linux RPM package installer. |
+| wktui_1.4.1_amd64.deb | Linux DEB package installer. |
+
+The Linux AppImage package is not an installer. It is a portable packaging of the application that can run directly without installation on a compatible Linux machine. For more information, see https://appimage.org/.
 
 **NOTE**: On Linux, to get _all_ the dependencies and have them installed in the correct order, you need to use the package manager to install the `rpm` or `deb` file. First, be sure to review the Linux prerequisites [here]({{< relref "/setup/prerequisites.md" >}}).
 

documentation/1.5/content/setup/prerequisites.md

@@ -29,7 +29,7 @@ These include:
  to generate one for you.
 
 
-{{% notice note %}} The WKT UI application is built using the Electron framework and as such, we support only the platforms and versions supported by [Electron](https://www.electronjs.org/docs/latest/tutorial/support#supported-platforms). For example, because of the Electron requirement for Fedora 24 or newer, we support _only_ versions 8.0 and higher of Oracle Linux, RedHat Linux, and CentOS Linux.
+{{% notice note %}} The WKT UI application is built using the Electron framework and as such, we support only the platforms and versions supported by [Electron](https://www.npmjs.com/package/electron); see the listing under Platform Support. For example, because of the Electron requirement for Fedora 24 or newer, we support _only_ versions 8.0 and higher of Oracle Linux, RedHat Linux, and CentOS Linux.
 {{% /notice %}}
 
 In addition to these local software dependencies, you will need a Kubernetes cluster to which you can deploy your

documentation/1.5/content/setup/quickstart/_index.md

@@ -0,0 +1,40 @@
++++
+title = "Quick Start Guide"
+date = 2019-02-22T15:27:38-05:00
+weight = 4
+pre = "<b> </b>"
+description = "Use the Quick Start guide to exercise WKT UI functionality and deploy a sample application."
++++
+
+This Quick Start guide provides a comprehensive tutorial designed to step you through WebLogic Kubernetes Toolkit UI (WKTUI)
+functionality and familiarize you with its capabilities. WKTUI is a desktop application that helps you create and deploy WebLogic
+domains into Kubernetes. Using this guide, you will deploy a sample WebLogic-based application to a Kubernetes cluster.
+
+Note that this walk-through is for demonstration purposes _only_, not for use in production. These instructions assume that you are already familiar with Kubernetes.
+For this exercise, you’ll need a Kubernetes cluster. If you need help setting one up, see these instructions for setting up an [Oracle Cloud Infrastructure
+Container Engine for Kubernetes (OKE) cluster](https://docs.oracle.com/en-us/iaas/Content/ContEng/Concepts/contengoverview.htm).
+
+The Quick Start guide is divided into the following sections:
+
+- [Prerequisites]({{< relref "/setup/quickstart/prereqs.md" >}})
+- [Get the ToDo List sample application]({{< relref "/setup/quickstart/get-todo-app.md" >}})
+- [Set up the WKTUI application]({{< relref "/setup/quickstart/set-up-wktui-app.md" >}})
+- [Select the Project Settings]({{< relref "/setup/quickstart/project-settings.md" >}})
+- [Create the WebLogic Deploy Tooling model]({{< relref "/setup/quickstart/create-wdt-model.md" >}})
+- [Create images with the WebLogic Image Tool]({{< relref "/setup/quickstart/create-images-with-wit.md" >}})
+- [WebLogic Kubernetes Operator (WKO)]({{< relref "/setup/quickstart/qs-kubernetes/" >}}) Track: follow these steps if you are interested in using a Kubernetes cluster without Verrazzano.
+ - [Configure Kubernetes Cluster Connectivity]({{< relref "/setup/quickstart/qs-kubernetes/k8s-client-config.md" >}})
+ - [Install the WebLogic Kubernetes Operator]({{< relref "/setup/quickstart/qs-kubernetes/k8s-wko.md" >}})
+ - [Deploy the Domain]({{< relref "/setup/quickstart/qs-kubernetes/k8s-weblogic-domain.md" >}})
+ - [Install and Configure the Ingress Controller]({{< relref "/setup/quickstart/qs-kubernetes/k8s-ingress-controller.md" >}})
+ - [Access the ToDo List Application]({{< relref "/setup/quickstart/qs-kubernetes/k8s-access-app.md" >}})
+- [Verrazzano (VZ)]({{< relref "/setup/quickstart/qs-verrazzano/" >}}) Track: follow these steps if you are interested in using a Kubernetes cluster with Verrazzano.
+ - [Configure Kubernetes cluster connectivity]({{< relref "/setup/quickstart/qs-verrazzano/vz-client-config.md" >}})
+ - [Install Verrazzano]({{< relref "/setup/quickstart/qs-verrazzano/vz-install.md" >}})
+ - [Deploy the Verrazzano Component for the WebLogic Domain]({{< relref "/setup/quickstart/qs-verrazzano/vz-component.md" >}})
+ - [Deploy the Verrazzano Application]({{< relref "/setup/quickstart/qs-verrazzano/vz-application.md" >}})
+ - [Access the ToDo List Application]({{< relref "/setup/quickstart/qs-verrazzano/vz-access-app.md" >}})
+- [Summary]({{< relref "/setup/quickstart/qs-summary/" >}})
+- [Advanced]({{< relref "/setup/quickstart/qs-advanced/" >}})
+ - [Offline Discover]({{< relref "/setup/quickstart/qs-advanced/offline-discover.md" >}})
+ - [Online Remote Discover]({{< relref "/setup/quickstart/qs-advanced/online-remote-discover.md" >}})

documentation/1.5/content/setup/quickstart/create-images-with-wit.md

@@ -0,0 +1,84 @@
+---
+title: "Create images with the WebLogic Image Tool"
+date: 2019-02-22T15:44:42-05:00
+draft: false
+weight: 6
+---
+
+WKTUI uses the WebLogic Image Tool (WIT) to build container images. Each Oracle Fusion Middleware (FMW) Domain Target Location option has its own image requirements.
+
+- Model-in-Image – MII has two approaches:
+ - Single Image – This approach uses a single image with Java, FMW, WDT, and the WDT model files all built into a single image. In WKTUI, we use the `Primary Image` tab to build such an image.
+ - Dual Images – This approach puts Java and FMW into one image, which WKTUI calls the primary image, and WDT and the WDT model files into a separate image, known as the auxiliary image. In this document, we refer to this as MII with Auxiliary Image.
+- Domain-in-Image – DII uses a single image approach but uses WDT and the WDT model files to create the domain inside the image.
+- Domain-on-PV – DoPV uses a single image with Java and FMW in it. The domain is created on the persistent volume by external means.
+
+Both MII with Auxiliary Image and Domain-on-PV have an image containing only software (Java and FMW) with no configuration. This provides several important, operational advantages:
+
+- Multiple domains can share the same software-only image since no domain-specific configuration is included. Updating hundreds of domains that all share the same image is as simple as updating the WebLogic Kubernetes Operator Domain custom resource specification to change the image. WKO will detect this change and perform a rolling update of the domain, starting with the Administration Server.
+- The Oracle Container Registry (OCR) distributes prebuilt images that you can use directly, after you log in and accept the terms and conditions. Oracle customers with an active support contract can access prebuilt images with the latest set of recommended patches. See https://container-registry.oracle.com for more information about the prebuilt images and to accept the terms and conditions for the repositories of interest.
+
+With DII and MII (without an auxiliary image), you would need to build new images for every domain to roll out a security fix across our entire set of domains. For those with large numbers of domains, this becomes a heavy burden, leading to less secure environments. To take advantage of these operational advantages, you will use MII with Auxiliary Image for the ToDo List domain.
+
+Go to the `Image` page, shown in the following image. 
+
+{{< img "Image Page" "images/image-page.png" >}}
+
+You could build your own primary image by enabling `Create New Primary Image`, which is off by default. To do this, you would need to download the Java 11 JDK and WebLogic Server 14.1.1 installers, fill out the form, and run `Create Primary Image`. Then, you would need to create an image repository in an image registry somewhere and push the newly created image there. When Oracle releases the next set of patches, you would have to do it again.
+
+Fortunately, you can simply use the prebuilt images in OCR. Log into [OCR](https://container-registry.oracle.com) and select the **Middleware** category. For those without Oracle Support credentials, make sure that you have accepted the terms and conditions for the `weblogic` repository. In the following image, note the green checkmark at the end of the `weblogic` repository row. For those with Oracle Support credentials, it is highly recommended to use the `weblogic_cpu` repository at the bottom of the page instead.
+
+{{< img "OCR" "images/ocr.png" >}}
+
+For this exercise, you will create a new auxiliary image. This is the default setting and the `Auxiliary Image` tab is active. Select the `Auxiliary Image` tab, as shown in the following image. 
+
+{{< img "Aux Image Tab" "images/aux-image-tab.png" >}}
+
+The first thing you need to decide is what image registry to use for the auxiliary image. For this exercise, you will use the Container Registry from the Oracle Cloud (OCIR) but feel free to substitute another image registry. We will try to point out where your image registry selection impacts the rest of the example. 
+
+
+After logging in to your Oracle Cloud account, select to the Container Registry option under the **Developer Services** category, as shown in the following image. 
+
+{{< img "OCIR Location" "images/ocir-location.png" >}}
+
+In the registry of your choosing, create a new private repository called `wktui-qs/todolist-aux`. Note the URL needed to access the new repository. For the OCIR repository, the URL is of the form `<region-abbreviation>.ocir.io/<tenancy-name>/wktui-qs/todolist-aux`, where region-abbreviation is something like `phx` (for the Phoenix region) and tenancy name is the name of the tenancy used to log in to `https://cloud.oracle.com`. For a listing of every available region, refer to this [table](https://docs.oracle.com/en-us/iaas/Content/Registry/Concepts/registryprerequisites.htm#Availab).
+
+To access this OCIR repository from Docker and Kubernetes, you need to use an Auth Token associated with your account in place of your password. To create an Auth Token, go to your User settings, select the Auth Tokens option under Resources, and click **Generate Token**, as shown in the following image. Make sure to retain a copy of the generated token, because this is the _only_ opportunity you will have to see it in clear text!
+
+{{< img "OCI Create Auth Token" "images/oci-create-auth-token.png" >}}
+
+Now that your Image Registry is ready, you simply fill out the `Auxiliary Image` tab in WKTUI. There are a couple of things to note before you fill out the form.
+
+- Most image registries require authentication to push an image. If you are using OCIR, the Auxiliary Image Registry Push Username and Auxiliary Image Registry Push Password must do the following:
+ - Username: Must be of the form `<tenancy-name>/<username>`.
+ - Password: Must be the value an Auth Token associated with the user’s account.
+- By default, WIT (and therefore WKTUI) use BusyBox as the base image for an auxiliary image. Because BusyBox typically comes from Docker Hub and Docker Hub has implemented anonymous pull request throttling, it is a good idea to enter a valid Docker Hub Username and Docker Hub Password to minimize the change of throttling-related errors while building the image.
+- You can change the base image simply by enabling `Use Custom Base Image` and filling out the form.
+- If your target platform is OpenShift, enable `Make Image Compatible with OpenShift` in the **Advanced** section of the page.
+
+With these things in mind, fill out the form using the data in the following table. If a field’s value is not provided, then leave it set to the default unless otherwise required for your environment.
+
+| Field Name | Value |
+| --- | --- |
+| `Auxiliary Image Tag` | `<image-repository-url>:1.0`; for example, `phx.ocir.io/mytenancy/wktui-qs/todolist:1.0` |
+| `Specify Auxiliary Image Push Credentials` | `ON` |
+| `Auxiliary Image Registry Push Username` | `<tenancy>/<username>`; for example, `mytenancy/fred.jones@mycompany.com` |
+| `Auxiliary Image Registry Push Password` | `<auth-token-value>`; for example, `z+M3C2UqRraHG73Z+.X8` |
+| `Use Custom Base Image` | `OFF` |
+| `Docker Hub Username` | Your Docker Hub account user name |
+| `Docker Hub Password` | Your Docker Hub account password |
+| `Download and Use Latest WebLogic Deploy Tooling Installer` | `ON` |
+| `Make Image Compatible with Open Shift` | `OFF` (unless required for your environment)) |
+
+After you complete the form, you are ready to create the auxiliary image. Click **Create Auxiliary Image** to have the application invoke WIT with the specified set of arguments to build the auxiliary image. The application prompts you twice prior to running WIT’s `createAuxImage` command:
+
+- You always should run **Prepare Model** prior to creating the auxiliary image. Because you have already done that, select `No` to continue without running Prepare Model. 
+- You need to choose the location to store the downloaded WDT installer. Choose the location and Click **Select**.
+
+The following image shows the application after successfully creating the auxiliary image.
+
+{{< img "Create AUX Image" "images/create-aux-image.png" >}}
+
+Now, you are ready to push the auxiliary image to the image registry. If running on macOS, you need to make sure that your Docker (or Podman) executable directory (for example, `$HOME/.rd/bin`, if using Rancher Desktop) is added to the `Extra Path Directories` table on the `Project Settings` page. Doing this allows Docker to find the executable it uses to interact with the macOS Keychain for storing credentials.
+
+Click **Push Auxiliary Image**. At this point, you are ready to shift your focus to the Kubernetes cluster. Remember, any change to the model files requires creating a new auxiliary image, which may require rerunning **Prepare Model** if fields were added to the model’s YAML file. We strongly recommend that you always increment the version number of the `Auxiliary Image Tag` field prior to creating and pushing a new image. This will make it very clear which image is in use.