Issue #371 - Documentation for alternate configuration directory

README.md

@@ -29,10 +29,13 @@ Many organizations are using WebLogic Server, with or without other Oracle Fusio
     - [ODL Configuration](site/odl_configuration.md)
     - [Configuring Oracle HTTP Server (OHS)](site/ohs_configuration.md)
     - [Configuring Oracle WebLogic Server Kubernetes Operator](site/kubernetes.md)
-    - [Variable Injection](site/variable_injection.md)
     - [Model Samples](site/samples/samples.md)
-    - [Model Filters](site/tool_filters.md)
     - [The Archive File](site/archive.md)
+- Configuration
+    - [Custom Configuration](site/config/custom_configuration.md)
+    - [Model Filters](site/tool_filters.md)
+    - [Type Definitions](site/type_def.md)
+    - [Variable Injection](site/variable_injection.md)
 - [Downloading and Installing](#downloading-and-installing-the-software)
 - [Developer Guide](site/developer/developer_guide.md)
 - [Known Issues](KnownIssues.md)

site/config/custom_configuration.md

@@ -0,0 +1,43 @@
+## Custom Configuration
+
+WDT allows you to create or extend the pre-installed type definitions, model filters, variable injectors, and target environments. Starting with WDT 1.10.0, these additional configuration files can be stored outside the `$WLSDEPLOY_HOME/lib` directory. This allows the files to remain in place if the WDT installation is moved or upgraded to a new version.
+
+To use a separate configuration directory, set the `WDT_CUSTOM_CONFIG` environment variable to the directory to be used for configuration. For example:
+```
+export WDT_CUSTOM_CONFIG=/etc/wdtconfig
+```
+
+The customized configuration files should be named and organized the same way they would be under the `$WLSDEPLOY_HOME/lib` directory. For example:
+```
+/etc/wdtconfig
+    injectors
+        *.json  (injector files)
+    typedefs
+        *.json  (typedef files)
+    targets
+        my-target
+            target.json
+            *.py  (filter files)
+    model_filters.json
+    model_variable_injector.json
+    variable_keywords.json
+```
+This is a full set of files that can be configured. You will need only to add the files you have created or extended. Details for each configuration type are found at the following links:
+- [Model Filters](../tool_filters.md)
+- [Type Definitions](../type_def.md) (see [example](#example-extending-a-type-definition) below)
+- [Variable Injection](../variable_injection.md)
+- [The Prepare Model Tool](../prepare.md) (target environments)
+
+The WDT tools will look for each configuration file under `$WDT_CUSTOM_CONFIG` if specified, then under `$WLSDEPLOY_HOME/lib`.
+
+### Example: Extending a Type Definition
+
+To extend the `WLS` type definition, follow these steps:
+- Create a directory to use for custom configurations, such as `/etc/wdtconfig`.
+- Define the `WDT_CUSTOM_CONFIG` environment variable to point to that directory.
+- Copy the file `$WLSDEPLOY_HOME/lib/typedefs/WLS.json` to the `$WDT_CUSTOM_CONFIG/typedefs` directory and rename it, for example `MY_WLS.json`.
+- Edit `MY_WLS.json` with any required changes.
+- Run the tool referencing the name of the new type definition, for example:
+```
+createDomain.cmd -oracle_home /wls12213 -domain_type MY_WLS ...
+```

site/prepare.md

@@ -9,21 +9,17 @@ from the model that are not compatible with the WebLogic Kubernetes Operator, re
 
 To use the Prepare Model Tool, simply run the `prepareModel` shell script with the correct arguments.  To see the list of valid arguments, simply run the shell script with the `-help` option (or with no arguments) for usage information.
 
-```
 To prepare model files, run the tool as follows:
-
-    $WLSDEPLOY_HOME/bin/prepareModel.sh -oracle_home /u01/wls12213 -model_file [command separed list of models] -target k8s -output_dir $HOME/k8soutput
-
+```
+$WLSDEPLOY_HOME/bin/prepareModel.sh -oracle_home /u01/wls12213 -model_file [command separed list of models] -target k8s -output_dir $HOME/k8soutput
 ```
 
-In the output directory, you will find
-
+In the output directory, you will find:
 ```
 model1.yaml
 model2.yaml
 create_k8s_secrets.sh
 k8s_variable.properties
-
 ```
 
 You can then customize the `k8s_variable.properties` and `create_k8s_secrets.sh` to provide environment specific values.
@@ -32,8 +28,9 @@ You can then customize the `k8s_variable.properties` and `create_k8s_secrets.sh`
 
 The '-target' parameter is referring to a file on the file system '$WLSDEPLOY_HOME/lib/target/<target value>/target.json'
 
-It has the format
+You also can configure a target in a [Custom Configuration](config/custom_configuration.md) directory, in `$WDT_CUSTOM_CONFIG/target/<target name>/target.json`. 
 
+It has the format:
 ```
 {
   "model_filters" : {
@@ -47,19 +44,21 @@ It has the format
 }
 ```
 
-The json file has several attributes that can be customized
+The JSON file has several attributes that can be customized
 
 | Name | Description |
 | --- | --- |
-| model_filters | Specify the filters json configuration for the target configuration.  This follows the same schema of [Model Filters](tool_filters.md). Note only discover is valid | 
-| variable_injectors | Specify the variable injector json configuration for the target configuration.  This follows the same schema of [Model Filters](tool_filters.md)|
+| model_filters | Specify the filters JSON configuration for the target configuration.  This follows the same schema of [Model Filters](tool_filters.md). Note only discover is valid | 
+| variable_injectors | Specify the variable injector JSON configuration for the target configuration.  This follows the same schema of [Model Filters](tool_filters.md)|
 | validation method | lax only |
 | credential_as_secret | true only |
 
 `"@@TARGET_CONFIG_DIR@@` resolves to the '$WDT_INSTALL/lib/target/<target value>' directory.  
 
-If there is a need to customize your own filers or injectors, you can
+If there is a need to customize your own filters or injectors, you can
 
 1. ```mkdir $WDT_INSTALL/lib/target/mytarget```
-2. Create a file named target.json follow the schema above in $WLSDEPLOY_HOME/lib/target/mytarget
+2. Create a file named `target.json` following the schema above in $WLSDEPLOY_HOME/lib/target/mytarget
 3. Run the prepareModel command using the parameter -target mytarget
+
+Another option is to configure a new target in a [Custom Configuration](config/custom_configuration.md) directory. Create the `target/<target name>/target.json` file in the `$WDT_CUSTOM_CONFIG` directory. 

site/tool_filters.md

@@ -19,6 +19,8 @@ def filter_model(model):
 
 Model filters are configured by creating a `model_filters.json` file in the `WLSDEPLOY_HOME/lib` directory. This file has separate sections for filters to be applied for specific tools.
 
+Another option is to configure model filters in a [Custom Configuration](config/custom_configuration.md) directory. Create the `model_filters.json` file in the `$WDT_CUSTOM_CONFIG` directory. 
+
 This example configures two filters for the Create Domain Tool: `fix-password.py` and `no-mail.py`, and one filter for the Discover Domain tool.
 
 ```json

site/type_def.md

@@ -76,7 +76,13 @@ WebLogic Server Deploy Tooling has an extensible domain type system.  The three
 }
 ```
 
-This file tells the Create Domain Tool which templates to use to create the domain, which server groups to target, and even which RCU schemas to create, all based on the installed version of WebLogic Server.  New domain types can be defined by creating a new JSON file with the same structure in the `WLSDEPLOY_HOME/lib/typedefs` directory.  For example, to define a `SOA` domain type for 12.2.1.3, add the `WLSDEPLOY_HOME/lib/typedefs/SOA.json` file with with similar content, as shown below.
+This file tells the Create Domain Tool which templates to use to create the domain, which server groups to target, and even which RCU schemas to create, all based on the installed version of WebLogic Server.
+
+New domain types can be defined by creating a new JSON file with the same structure in the `WLSDEPLOY_HOME/lib/typedefs` directory.
+
+Another option is to create this file in the [Custom Configuration](config/custom_configuration.md) directory `$WDT_CUSTOM_CONFIG/typedefs`. 
+
+For example, to define a `SOA` domain type for 12.2.1.3, add the `typedefs/SOA.json` file with similar content, as shown below.
 
 ```json
 {

site/variable_injection.md

@@ -2,7 +2,11 @@
 
 The Variable Injector Tool is used to tokenize a model with variables. The values for these variables are assigned using an external property file. This facilitates using the same domain model to create new domains in different environments. The Variable Injector Tool can be run as an option in the Discover Domain Tool, or from the standalone command-line interface.
 
-To enable the Variable Injector Tool during the Discover Domain Tool run, create a variable injector configuration by placing a JSON file named `model_variable_injector.json` into the `\<WLSDEPLOY\>/lib` directory using one or more of the pre-defined keywords and/or a CUSTOM list of files. A keyword points to an injector directive file. The tool applies the directives to the attributes in a model, and if the directive matches an attribute, then a property token with a unique variable name is injected into the model and replaces the attribute value. The variable name and model attribute value are placed into the external variable properties file.
+To enable the Variable Injector Tool during the Discover Domain Tool run, create a variable injector configuration by placing a JSON file named `model_variable_injector.json` into the `<WLSDEPLOY>/lib` directory using one or more of the pre-defined keywords and/or a CUSTOM list of files.
+
+Another option is to configure variable injection in a [Custom Configuration](config/custom_configuration.md) directory. Create the `model_variable_injector.json` file in the `$WDT_CUSTOM_CONFIG` directory. 
+
+A keyword points to an injector directive file. The tool applies the directives to the attributes in a model, and if the directive matches an attribute, then a property token with a unique variable name is injected into the model and replaces the attribute value. The variable name and model attribute value are placed into the external variable properties file.
 
 **NOTE**: Variable injection on an attribute is only performed once. The property token is not replaced by any subsequent matches.
 
@@ -23,7 +27,7 @@ The supported keywords are as follows:
 
 - `URL` - All MBean URL attribute values in the model are injected with a variable.
 
-**NOTE**: The directives used by each pre-defined keyword are defined in an injector JSON file that is located in the `\<WLSDEPLOY\>/lib/injectors` folder. These files should not be changed, but could be used as is.
+**NOTE**: The directives used by each pre-defined keyword are defined in an injector JSON file that is located in the `<WLSDEPLOY>/lib/injectors` folder. These files should not be changed, but could be used as is.
 
 Here is an example of a `model_variable_injector.json` file using the PORT keyword.
 
@@ -80,7 +84,7 @@ Server.soa_server2.ListenPort=8001
 Server.soa_server2.SSL.ListenPort=8002
 ```
 
-To specify the name and location of the variable properties file for the Discover Domain Tool, use the argument `-variable_properties_file` on the command line. Usage of the `variable_properties_file` argument without the presence of the model variable injector file in the `\<WLSDEPLOY\>/lib` directory will cause an error condition and the tool will exit. If the model variable injector file exists in the directory, but the command-line argument is not used, the variable properties file is created with the following defaults:
+To specify the name and location of the variable properties file for the Discover Domain Tool, use the argument `-variable_properties_file` on the command line. Usage of the `variable_properties_file` argument without the presence of the model variable injector file in the `<WLSDEPLOY>/lib` directory will cause an error condition and the tool will exit. If the model variable injector file exists in the directory, but the command-line argument is not used, the variable properties file is created with the following defaults:
 * If the `model_file` command-line argument is used on the Discover Domain Tool run, the properties file name and location will be the same as the model file, with the file extension `.properties`.
 * If only the archive file argument is present, the archive file name and location will be used.