revise docs (#90)

* revise docs

* Add important first step to procedure

Author: rosemarymarano

README.md

@@ -11,32 +11,45 @@ image.
 ## Features
 
 The Image Tool provides three functions within the main script:
-  - [Create Image](site/create-image.md) - The `create` command creates a new Docker image and installs the requested 
+  - [Create Image](site/create-image.md) - The `create` command creates a new Docker image and installs the requested
   Java and WebLogic software.  Additionally, you can create a WebLogic domain in the image at the same time.
-  - [Update Image](site/update-image.md) - The `update` command creates a new Docker image by applying WebLogic patches 
-  to an existing image.  Additionally, you can create a WebLogic domain if one did not exist previously, update an 
+  - [Update Image](site/update-image.md) - The `update` command creates a new Docker image by applying WebLogic patches
+  to an existing image.  Additionally, you can create a WebLogic domain if one did not exist previously, update an
   an existing domain, or deploy an application.
   - [Cache](site/cache.md) - The Image Tool maintains metadata on the local file system for patches and installers.  
   The `cache` command can be used to manipulate the local metadata.
 
 ## Prerequisites
 
-- Docker client and daemon on the build machine, with minimum Docker version Docker 18.03.1.ce.
-- Installers for WebLogic Server and JDK from OTN / Oracle e-Delivery.
-- (For patches) Oracle support credentials.
-- Bash version 4.0 or higher to enable the `<tab>` command complete feature.
+- Docker client and daemon on the build machine, with minimum Docker version 18.03.1.ce.
+- Installers for WebLogic Server and JDK from the [Oracle Software Delivery Cloud](https://edelivery.oracle.com).
+- For patches, [Oracle Support](https://www.oracle.com/technical-resources/) credentials.
+- Bash version 4.0 or later, to enable the `<tab>` command complete feature.
 
 ## Setup
 
-- Build the project (`mvn clean package`), to create the ZIP installer in ./imagetool/target.
+- Build the project (`mvn clean package`) to create the ZIP installer in `./imagetool/target`.
 - Unzip the release ZIP file to a desired location.
-- For Linux environment `cd your_unzipped_location/bin` and `source setup.sh`. 
-- For Windows environment `cd your_unzipped_location\bin` and `.\imagetool.cmd`. 
-- Run `imagetool help` to show the help screen.
+- For Linux environment, `cd your_unzipped_location/bin` and `source setup.sh`.
+- For Windows environment, `cd your_unzipped_location\bin` and `.\imagetool.cmd`.
+- Run `imagetool help` to show the help text.
 
 ## Quick Start
 
-[Image Tool Quick Start Guide](site/quickstart.md)
+Use the [Quick Start](site/quickstart.md) guide to create a Linux-based WebLogic Docker image.
+
+## Samples
+
+* [Create an image with full Internet access](site/create-image-with-internet.md)
+* [Create an image with no Internet access](site/create-image-no-internet.md)
+* [Patch an existing image](site/patching-image.md)
+* [Create an image with a WebLogic domain using the WebLogic Deploy Tool](site/create-image-wdt.md)
+
+## Additional tasks
+
+* [Cleanup](site/cleanup.md)
+* [Logging](site/logging.md)
+
 
 ## Copyright
 Copyright (c) 2019 Oracle and/or its affiliates.  All rights reserved.

site/argument-file.md

@@ -0,0 +1,26 @@
+# Use an argument file
+
+You can save all arguments passed for the Image Tool in a file, then use the file as a parameter.
+
+For example, create a file called `build_args`:
+
+```bash
+create
+--type wls
+--version 12.2.1.3.0
+--tag wls:122130
+--user [email protected]
+--httpProxyUrl http://mycompany-proxy:80
+--httpsProxyUrl http://mycompany-proxy:80
+--passwordEnv MYPWD
+
+```
+
+Use it on the command line, as follows:
+
+```bash
+imagetool @/path/to/build_args
+```
+
+### Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

site/cache.md

@@ -1,28 +1,30 @@
 # Cache
 
-The Image Tool maintains a local file cache store, this store is used to look up where the Java,
-WebLogic installers, and WebLogic patches reside in the local file system.
-                                                                         
-By default, it is stored in the user's ```$HOME/cache``` directory.  Under this directory, the lookup information is
-stored in the file ```.metadata```.  All automatically downloaded patches also reside in this directory.  
-                                                                         
-This default cache store location can be changed by setting the environment variable WLSIMG_CACHEDIR
+The Image Tool maintains a local file cache store. This store is used to look up where the Java, WebLogic Server installers, and WebLogic Server patches reside in the local file system.
 
-The `cache` command can be used to manipulate the local file cache. There are several subcommands of the cache feature:
+By default, the cache store is located in the user's ```$HOME/cache``` directory.  Under this directory, the lookup information is stored in the ```.metadata``` file.  All automatically downloaded patches also reside in this directory.  
 
+You can change the default cache store location by setting the environment variable `WLSIMG_CACHEDIR`:
+
+```bash
+export WLSIMG_CACHEDIR="/path/to/cachedir"
 ```
-Usage: imagetool cache [COMMAND]
-List and set cache options
 
-Commands:
+You use the `cache` command to manipulate the local file cache. There are several subcommands for the cache feature.
 
-  listItems     List cache contents
-  addInstaller  Add cache entry for wls, fmw, jdk or wdt installer
-  addPatch      Add cache entry for wls|fmw patch or psu
-  addEntry      Command to add a cache entry. Use caution
-  deleteEntry   Command to delete a cache entry
-  help          Displays help information about the specified command
 ```
+Usage: imagetool cache [OPTIONS]
+List and set cache options
+```
+
+| Option | Description |
+| --- | --- |
+|`listItems`| List cache contents. |
+|`addInstaller` | Add cache entry for `wls`, `fmw`, `jdk`, or `wdt` installer. |
+| `addPatch` | Add cache entry for `wls` or `fmw` patch, or `psu`.  |
+| `addEntry` | Add a cache entry. Use with caution. |  
+| `help` | Display help information for the specified command.|
+
 
 ## Usage scenarios
 
@@ -44,21 +46,21 @@ Commands:
     imagetool cache addInstaller --type jdk --version 8u202 --path /path/to/local/jdk.tar.gz
     ```
 
-- `addPatch`: Add a patch to the cache. This command verifies if the path points to a valid patch by querying the Oracle support portal.
+- `addPatch`: Add a patch to the cache. This command verifies if the path points to a valid patch by querying the Oracle Support portal.
     ```
     imagetool cache addPatch --type wls --patchId 12345678_12.2.1.3.0 --path /path/to/patch.zip
     ```
-Note:  When adding a patch to the cache store. The patchId should be in the following format:  99999999_9.9.9.9.99999  The first 8 digits is the patch id, followed by an underscore and then release number.  This is needed if you want to distinguish a patch that has different versions of the patch.  
+    **Note**:  When adding a patch to the cache store, the `patchId` should be in the following format:  `99999999_9.9.9.9.99999`  The first 8 digits is the patch ID, followed by an underscore, and then the release number.  This is needed if you want to distinguish a patch that has different patch versions.  
 
-For example, patch 29135930 has several different versions from Oracle support, one for each release where the bug is fixed.
+    For example, patch `29135930` has several different versions in Oracle Support, one for each release in which the bug is fixed.
 
 | Patch Name | Release |
 | ---------|---------|
-| 29135930 | 12.2.1.3.190416|
-| 29135930 | 12.2.1.3.0 |
-| 29135930 | 12.2.1.3.18106 |
+| `29135930` | `12.2.1.3.190416`|
+| `29135930` | `12.2.1.3.0` |
+| `29135930` | `12.2.1.3.18106` |
 
-If you have downloaded the release version ```12.2.1.3.190416``` of the patch, then you should use the argument as ```--patchId 29135930_12.2.1.3.190416```
+If you downloaded the release version ```12.2.1.3.190416``` of the patch, then you should use the argument ```--patchId 29135930_12.2.1.3.190416```.
 
 - `addEntry`: Consider this an expert mode where you can add key value pairs to the cache without any validation.
     ```

site/cleanup.md

@@ -0,0 +1,21 @@
+# Cleanup
+
+The Image Tool creates a temporary directory, prefixed by ```wlsimgbuilder_temp```,
+every time it runs.  Under normal circumstances, this directory will be deleted. However,
+if the process is aborted or the tool is unable to remove the directory, you can delete it manually.
+
+By default, the temporary directory is created under the user's home directory. If you do not want it created under the home directory, set the environment variable:
+
+ ```bash
+export WLSIMG_BLDDIR="/path/to/dir"
+```
+
+
+If you see dangling images after the build, use the following command to remove them:
+
+```bash
+docker rmi $(docker images --filter "dangling=true" -q --no-trunc)
+```
+
+### Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

site/create-image-no-internet.md

@@ -0,0 +1,57 @@
+# Create an image without Internet access
+
+
+In this use case, because there is no Internet access, you will need to download all the installers and
+patches, plus set up the cache.  Also, you must provide a base operating system image that has the following packages installed.
+
+```bash
+gzip
+tar
+unzip
+```
+
+## Steps
+
+1. Download these Java and WebLogic installers from the [Oracle Software Delivery Cloud](https://edelivery.oracle.com)
+and save them in a directory of your choice, for example, `/home/acmeuser/wls-installers`:
+
+     `fmw_12.2.1.3.0_wls_Disk1_1of1.zip`\
+     `jdk-8u202-linux-x64.tar.gz`
+
+
+2. Use the [Cache Tool](cache.md) to add the installers:
+
+    ```bash
+    imagetool cache addInstaller --type jdk --version 8u202 --path /home/acmeuser/wls-installers/jdk-8u202-linux-x64.tar.gz
+    ```
+
+    ```bash
+    imagetool cache addInstaller --type wls --version 12.2.1.3.0 --path /home/acmeuser/wls-installers/fmw_12.2.1.3.0_wls_Disk1_1of1.zip
+    ```
+
+3. For each WebLogic patch, download it from [Oracle Support](https://support.oracle.com/keystone/) and set up the cache.
+
+    For example, if you download patch number `27342434` for WebLogic Server version 12.2.1.3.0:
+
+  ```bash
+  imagetool cache addPatch --patchId 27342434_12.2.1.3.0 --path /home/acmeuser/cache/p27342434_122130_Generic.zip
+  ```
+
+  **Note**: Refer to the [Cache](cache.md) commands for the format of ```patchId```.
+
+4. Then, run the command to create the image:
+
+  ```bash
+  imagetool create --fromImage myosimg:latest --tag wls:12.2.1.3.0 --patches 27342434 --version 12.2.1.3.0
+  ```
+
+5. Occasionally, a WebLogic Server patch will require patching the OPatch binaries before applying them.  We recommend downloading the latest OPatch patch and setting up the cache.  
+
+    For example, if the latest OPatch patch is `28186730`, `13.9.4.0.0`.  After downloading it from Oracle Support, you can use this command to set up the cache:
+
+  ```bash
+  imagetool cache addPatch --patchId 28186730_13.9.4.0.0 --path /home/acmeuser/cache/p28186730_139400_Generic.zip
+  ```
+
+## Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

site/create-image-wdt.md

@@ -0,0 +1,40 @@
+# Create an image with a WebLogic domain using the WebLogic Deploy Tool
+
+The Image Tool lets you create a customized WebLogic domain in the image using the [WebLogic Deploy Tool](https://github.com/oracle/weblogic-deploy-tooling).
+
+## Steps
+
+1. Create the image, as directed in the [Quick Start](quickstart.md) guide.
+
+2. Download the [WebLogic Deploy Tool](https://github.com/oracle/weblogic-deploy-tooling/releases), and then add it to the cache store:
+
+```bash
+imagetool cache addInstaller --type wdt --version 0.22 --path /home/acmeuser/cache/weblogic-deploy.zip
+```
+
+3. Provide the command-line options for the WebLogic Deploy Tool:
+
+```bash
+imagetool create --fromImage myosimg:latest --tag wls:12.2.1.3.0  --version 12.2.1.3.0  --wdtVersion 1.4.0 --wdtArchive /home/acmeuser/wdt/domain1.zip --wdtDomainHome /u01/domains/simple_domain
+```
+
+The parameter mappings between the Image Tool and the WebLogic Deploy Tool are:
+
+| Image Tool         | WebLogic Deploy Tool | Default  |
+|--------------------|-------------------------|--------|
+| `--wdtArchive`       | `-archive_file`           |   |
+| `--wdtModel`         | `-model_file`             |   |
+| `--wdtVariables`     | `-variable_file`          |   |
+| `--wdtRunRCU`        | `-run_rcu`                | `false`  |
+| `--wdtDomainHome`    | `-domain_home`            |   |
+| `--wdtDomainType`     | `-domain_type`           |  `WLS` |
+
+
+ If you do not specify ```--wdtDomainHome```, the domain will be created under ```/u01/domains/base_domain```.
+
+**Note**: If you are creating a JRF domain and want WebLogic Deploy Tool to create the RCU schemas for you, you can
+specify the connection information in the model. See [Specifying RCU
+information in the model](https://github.com/oracle/weblogic-deploy-tooling/blob/master/site/rcuinfo.md).
+
+## Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

site/create-image-with-internet.md

@@ -0,0 +1,77 @@
+# Create an image with full Internet access
+
+The Image Tool supports creating Linux-based WebLogic Docker images, applying WebLogic patches, and creating WebLogic domains.  It can be used with or without Internet access.
+
+In this use case, the Image Tool will:
+
+1. Start with a base-level operating system image (`oraclelinux:7-slim`).
+2. Update the image with the necessary packages for installing WebLogic Server.
+3. Install Java and WebLogic Server.
+
+## Steps
+
+1. Download these Java and WebLogic installers from the [Oracle Software Delivery Cloud](https://edelivery.oracle.com)
+and save them in a directory of your choice, for example, `/home/acmeuser/wls-installers`:
+
+     `fmw_12.2.1.3.0_wls_Disk1_1of1.zip`\
+     `jdk-8u202-linux-x64.tar.gz`
+
+
+2. Use the [Cache Tool](cache.md) to add the installers:
+
+    ```bash
+    imagetool cache addInstaller --type jdk --version 8u202 --path /home/acmeuser/wls-installers/jdk-8u202-linux-x64.tar.gz
+    ```
+
+    ```bash
+    imagetool cache addInstaller --type wls --version 12.2.1.3.0 --path /home/acmeuser/wls-installers/fmw_12.2.1.3.0_wls_Disk1_1of1.zip
+    ```
+
+    **Note**:  The value of the version must be a valid WebLogic Server version number. This version number is used to verify and find the correct patch file to download from Oracle Support.  The format of the version is a 5 digits tuple, separated by period.  For example,  ```12.2.1.3.0``` ```12.1.3.0.0```
+
+3. Create the image using the [Create Tool](create-image.md) commands. For example:
+
+  ```bash
+  imagetool create --tag wls:12.2.1.3.0 --latestPSU --version 12.2.1.3.0 --user  [email protected] --passwordEnv MYPWD  
+  ```
+
+   Where ```--user --passwordEnv``` provides the credentials for a user who is entitled to download patches from Oracle Support.
+
+ **NOTE**: You can provide the password in one of the three ways:
+
+ * Plain text
+ * Environment variable
+ * File containing the password
+
+
+You will see the Docker command output as the tool runs:
+
+```bash
+[2019-05-28 10:37:02] [com.oracle.weblogic.imagetool.cli.menu.CreateImage] [INFO   ] tmp directory used for build
+context: /home/acmeuser/wlsimgbuilder_temp8791654163579491583
+[2019-05-28 10:37:09] [com.oracle.weblogic.imagetool.cli.menu.CreateImage] [INFO   ] docker cmd = docker build
+--force-rm --rm=true --no-cache --tag wls:12.2.1.3.0 --build-arg http_proxy=http://company-proxy.com:80 --build-arg
+https_proxy=http://company-proxy.com:80 --build-arg WLS_PKG=fmw_12.2.1.3.0_wls_Disk1_1of1.zip --build-arg
+JAVA_PKG=jdk-8u201-linux-x64.tar.gz --build-arg PATCHDIR=patches /home/acmeuser/wlsimgbuilder_temp8791654163579491583
+Sending build context to Docker daemon   1.08GB
+
+Step 1/46 : ARG BASE_IMAGE=oraclelinux:7-slim
+...
+Removing intermediate container 57ccb9fff56b
+ ---> 18d366fc3da4
+Successfully built 18d366fc3da4
+Successfully tagged wls:12.2.1.3.0
+```
+
+3. To verify that the image was created, use the `docker images` command:
+
+```bash
+docker images
+
+REPOSITORY          TAG                 IMAGE ID            CREATED              SIZE
+wls                 12.2.1.3.0          18d366fc3da4        About a minute ago   1.41GB
+oraclelinux         7-slim              f7512ac13c1b        6 weeks ago          118MB
+
+```
+## Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

site/logging.md

@@ -0,0 +1,8 @@
+# Logging
+
+In some circumstances, it may be helpful to turn on debugging to reveal more information.  
+
+The Image Tool uses the standard `logging.properties` file under the tool's ```bin``` directory.
+
+### Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.

site/patching-image.md

@@ -0,0 +1,27 @@
+# Patch an existing image
+
+This example shows you how to apply WebLogic Server patches to an existing image.
+You can download patches using the Image Tool or by manually downloading them.
+
+## Steps
+
+1. Create the image, as directed in the [Quick Start](quickstart.md) guide.
+
+2. For each WebLogic patch, download it from [Oracle Support](https://support.oracle.com/keystone/) and set up the cache.
+
+    For example, to download patch number `27342434` for WebLogic Server version 12.2.1.3.0:
+
+  ```bash
+  imagetool cache addPatch --patchId 27342434_12.2.1.3.0 --path /home/acmeuser/cache/p27342434_122130_Generic.zip
+  ```
+
+  **Note**: Refer to the [Cache](cache.md) commands for the format of ```patchId```.
+
+3. Use the [`imagetool update`](update-image.md) command to update the image:
+
+  ```bash
+  imagetool update --fromImage wls:12.2.1.3.0 --tag wls:12.2.1.3.4 --patches 27342434
+  ```
+
+## Copyright
+Copyright (c) 2019 Oracle and/or its affiliates. All rights reserved.