Skip to content

Commit 0fdd9d7

Browse files
ddsharpeddsharpe
authored
Merge pull request #245 from oracle/readme-TOC
Updated README with TOC
2 parents a2ba9b3 + 3a3babe commit 0fdd9d7

File tree

9 files changed

+862
-841
lines changed

9 files changed

+862
-841
lines changed

‎README.md

Lines changed: 30 additions & 841 deletions
Large diffs are not rendered by default.

‎site/create.md

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
## The Create Domain Tool
2+
3+
The Create Domain Tool uses a model and WLST offline to create a domain. To use the tool, at a minimum, the model must specify the domain's administrative password in the `domainInfo` section of the model, as shown below.
4+
5+
```yaml
6+
domainInfo:
7+
AdminPassword: welcome1
8+
```
9+
10+
Using the model above, simply run the `createDomain` tool, specifying the type of domain to create and where to create it.
11+
12+
weblogic-deploy\bin\createDomain.cmd -oracle_home c:\wls12213 -domain_type WLS -domain_parent d:\demo\domains -model_file MinimalDemoDomain.yaml
13+
14+
Clearly, creating an empty domain with only the template-defined servers is not very interesting, but this example just reinforces how sparse the model can be. When running the Create Domain Tool, the model must be provided either inside the archive file or as a standalone file. If both the archive and model files are provided, the model file outside the archive will take precedence over any that might be inside the archive. If the archive file is not provided, the Create Domain Tool will create the `topology` section only (using the `domainInfo` section) of the model in the domain. This is because the `resources` and `appDeployments` sections of the model can reference files from the archive so to create the domain with the model-defined resources and applications, an archive file must be provided--even if the model does not reference anything in the archive. At some point in the future, this restriction may be relaxed to require the archive only if it is actually needed.
15+
16+
The Create Domain Tool understands three domain types: `WLS`, `RestrictedJRF`, and `JRF`. When specifying the domain type, the Oracle Home must match the requirements for the domain type. Both `RestrictedJRF` and `JRF` require an Oracle Home with the FMW Infrastucture (also known as JRF) installed. When creating a JRF domain, the RCU database information must be provided as arguments to the `createDomain` script. Note that the tool will prompt for any passwords required. Optionally, they can be piped to standard input (for example, `stdin`) of the script, to make the script run without user input. For example, the command to create a JRF domain looks like the one below. Note that this requires the user to have run RCU prior to running the command.
17+
18+
weblogic-deploy\bin\createDomain.cmd -oracle_home c:\jrf12213 -domain_type JRF -domain_parent d:\demo\domains -model_file DemoDomain.yaml -rcu_db mydb.example.com:1539/PDBORCL -rcu_prefix DEMO
19+
20+
To have the Create Domain Tool run RCU, simply add the `-run_rcu` argument to the previous command line and the RCU schemas will be automatically created. Be aware that when the tool runs RCU, it will automatically drop any conflicting schemas that already exist with the same RCU prefix prior to creating the new schemas!
21+
22+
The Create Domain Tool has an extensible domain type system. The three built-in domain types (`WLS`, `RestrictedJRF`, and `JRF`) are defined in JSON files of the same name in the `WLSDEPLOY_HOME/lib/typedefs` directory. For example, the `JRF` domain type is defined in the `WLSDEPLOY_HOME/lib/typedefs/JRF.json` file whose contents look like those shown below.
23+
24+
```json
25+
{
26+
"copyright": "Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.",
27+
"license": "The Universal Permissive License (UPL), Version 1.0",
28+
"name": "JRF",
29+
"description": "JRF type domain definitions",
30+
"versions": {
31+
"12.1.2": "JRF_1212",
32+
"12.1.3": "JRF_1213",
33+
"12.2.1": "JRF_12CR2",
34+
"12.2.1.3": "JRF_12213"
35+
},
36+
"definitions": {
37+
"JRF_1212" : {
38+
"baseTemplate": "@@WL_HOME@@/common/templates/wls/wls.jar",
39+
"extensionTemplates": [
40+
"@@ORACLE_HOME@@/oracle_common/common/templates/wls/oracle.jrf_template_12.1.2.jar",
41+
"@@ORACLE_HOME@@/oracle_common/common/templates/wls/oracle.jrf.ws.async_template_12.1.2.jar",
42+
"@@ORACLE_HOME@@/oracle_common/common/templates/wls/oracle.wsmpm_template_12.1.2.jar",
43+
"@@ORACLE_HOME@@/em/common/templates/wls/oracle.em_wls_template_12.1.2.jar"
44+
],
45+
"serverGroupsToTarget" : [ "JRF-MAN-SVR", "WSMPM-MAN-SVR" ],
46+
"rcuSchemas": [ "MDS", "IAU", "IAU_VIEWER", "IAU_APPEND", "OPSS" ]
47+
},
48+
"JRF_1213" : {
49+
"baseTemplate": "@@WL_HOME@@/common/templates/wls/wls.jar",
50+
"extensionTemplates": [
51+
"@@ORACLE_HOME@@/oracle_common/common/templates/wls/oracle.jrf_template_12.1.3.jar",
52+
"@@ORACLE_HOME@@/oracle_common/common/templates/wls/oracle.jrf.ws.async_template_12.1.3.jar",
53+
"@@ORACLE_HOME@@/oracle_common/common/templates/wls/oracle.wsmpm_template_12.1.3.jar",
54+
"@@ORACLE_HOME@@/em/common/templates/wls/oracle.em_wls_template_12.1.3.jar"
55+
],
56+
"serverGroupsToTarget" : [ "JRF-MAN-SVR", "WSMPM-MAN-SVR" ],
57+
"rcuSchemas": [ "MDS", "IAU", "IAU_VIEWER", "IAU_APPEND", "OPSS" ]
58+
},
59+
"JRF_12CR2": {
60+
"baseTemplate": "Basic WebLogic Server Domain",
61+
"extensionTemplates": [
62+
"Oracle JRF WebServices Asynchronous services",
63+
"Oracle WSM Policy Manager",
64+
"Oracle Enterprise Manager"
65+
],
66+
"serverGroupsToTarget": [ "JRF-MAN-SVR", "WSMPM-MAN-SVR" ],
67+
"rcuSchemas": [ "MDS", "IAU", "IAU_VIEWER", "IAU_APPEND", "OPSS" ]
68+
},
69+
"JRF_12213": {
70+
"baseTemplate": "Basic WebLogic Server Domain",
71+
"extensionTemplates": [
72+
"Oracle JRF WebServices Asynchronous services",
73+
"Oracle WSM Policy Manager",
74+
"Oracle Enterprise Manager"
75+
],
76+
"serverGroupsToTarget": [ "JRF-MAN-SVR", "WSMPM-MAN-SVR" ],
77+
"rcuSchemas": [ "WLS", "MDS", "IAU", "IAU_VIEWER", "IAU_APPEND", "OPSS" ]
78+
}
79+
}
80+
}
81+
```
82+
83+
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 version of WebLogic Server installed. 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 contents like those shown below.
84+
85+
```json
86+
{
87+
"name": "SOA",
88+
"description": "SOA type domain definitions",
89+
"versions": {
90+
"12.2.1.3": "SOA_12213"
91+
},
92+
"definitions": {
93+
"SOA_12213": {
94+
"baseTemplate": "Basic WebLogic Server Domain",
95+
"extensionTemplates": [
96+
"Oracle SOA Suite"
97+
],
98+
"serverGroupsToTarget": [ "JRF-MAN-SVR", "WSMPM-MAN-SVR", "SOA-MGD-SVRS" ],
99+
"rcuSchemas": [ "STB", "WLS", "MDS", "IAU", "IAU_VIEWER", "IAU_APPEND", "OPSS", "UCSUMS", "SOAINFRA" ]
100+
}
101+
}
102+
}
103+
```
104+
105+
After the new domain `typedef` file exists, simply specify the new domain type name to the `createDomain` script, being sure to reference an Oracle Home with the required components installed. For pre-12.2.1 versions, the `-wlst_path` argument must be used to point to the product home where the appropriate WLST shell script exists; for example, for SOA 12.1.3, add `-wlst_path <ORACLE_HOME>/soa` so that the tool uses the WLST shell script with the proper environment for SOA domains. In 12.2.1 and later, this is no longer necessary because the WLST shell script in the standard `<ORACLE_HOME>oracle_common/common/bin` directory will automatically load all components in the Oracle Home. Using the new domain type, simply run the following command to run RCU and create the SOA domain with all of its resources and applications deployed.
106+
107+
weblogic-deploy\bin\createDomain.cmd -oracle_home d:\SOA12213 -domain_type SOA -domain_parent d:\demo\domains -model_file DemoDomain.yaml -archive_file DemoDomain.zip -variable_file DemoDomain.properties -run_rcu -rcu_db mydb.example.com:1539/PDBORCL -rcu_prefix DEMO
108+
109+
To create more complex domains with clusters of different types, it is necessary to control the targeting of server groups to managed servers. By default, all server groups in the domain type definition are targeted to all managed servers. To create a SOA domain with SOA and OSB clusters, simply add the OSB template and server group to the SOA domain definition, as shown below.
110+
111+
```json
112+
{
113+
"name": "SOA",
114+
"description": "SOA type domain definitions",
115+
"versions": {
116+
"12.2.1.3": "SOA_12213"
117+
},
118+
"definitions": {
119+
"SOA_12213": {
120+
"baseTemplate": "Basic WebLogic Server Domain",
121+
"extensionTemplates": [
122+
"Oracle SOA Suite",
123+
"Oracle Service Bus"
124+
],
125+
"serverGroupsToTarget": [ "JRF-MAN-SVR", "WSMPM-MAN-SVR", "SOA-MGD-SVRS", "OSB-MGD-SVRS-COMBINED" ],
126+
"rcuSchemas": [ "STB", "WLS", "MDS", "IAU", "IAU_VIEWER", "IAU_APPEND", "OPSS", "UCSUMS", "SOAINFRA" ]
127+
}
128+
}
129+
}
130+
```
131+
132+
Then, use the `ServerGroupTargetingLimits` map in the `domainInfo` section to limit the targeting of the Web Services Manager, SOA, and OSB server groups to the `soa_cluster` or `osb_cluster`, as appropriate. In the example below, notice that the `JRF-MAN-SVR` server group is not listed; therefore, it will use the default targeting and be targeted to all managed servers. The value of each element in this section is a logical list of server and/or cluster names. As shown in the example, the value for each server group can be specified as a list, a comma-separated string, or a single-valued string. There is no semantic difference between listing a cluster's member server names versus using the cluster name; the example uses these simply to show what is possible.
133+
134+
```$yaml
135+
domainInfo:
136+
AdminUserName: weblogic
137+
AdminPassword: welcome1
138+
ServerStartMode: prod
139+
ServerGroupTargetingLimits:
140+
'WSMPM-MAN-SVR': soa_cluster
141+
'SOA-MGD-SVRS': 'soa_server1,soa_server2'
142+
'OSB-MGD-SVRS-COMBINED': [ osb_server1, osb_server2 ]
143+
144+
topology:
145+
Name: soa_domain
146+
AdminServerName: AdminServer
147+
Cluster:
148+
soa_cluster:
149+
osb_cluster:
150+
Server:
151+
AdminServer:
152+
ListenAddress: myadmin.example.com
153+
ListenPort: 7001
154+
Machine: machine1
155+
SSL:
156+
Enabled: true
157+
ListenPort: 7002
158+
soa_server1:
159+
ListenAddress: managed1.example.com
160+
ListenPort: 8001
161+
Cluster: soa_cluster
162+
Machine: machine2
163+
SSL:
164+
Enabled: true
165+
ListenPort: 8002
166+
soa_server2:
167+
ListenAddress: managed2.example.com
168+
ListenPort: 8001
169+
Cluster: soa_cluster
170+
Machine: machine3
171+
SSL:
172+
Enabled: true
173+
ListenPort: 8002
174+
osb_server1:
175+
ListenAddress: managed1.example.com
176+
ListenPort: 9001
177+
Cluster: osb_cluster
178+
Machine: machine2
179+
SSL:
180+
Enabled: true
181+
ListenPort: 9002
182+
osb_server2:
183+
ListenAddress: managed2.example.com
184+
ListenPort: 9001
185+
Cluster: osb_cluster
186+
Machine: machine3
187+
SSL:
188+
Enabled: true
189+
ListenPort: 9002
190+
UnixMachine:
191+
machine1:
192+
NodeManager:
193+
ListenAddress: myadmin.example.com
194+
ListenPort: 5556
195+
machine2:
196+
NodeManager:
197+
ListenAddress: managed1.example.com
198+
ListenPort: 5556
199+
machine3:
200+
NodeManager:
201+
ListenAddress: managed2.example.com
202+
ListenPort: 5556
203+
SecurityConfiguration:
204+
NodeManagerUsername: weblogic
205+
NodeManagerPasswordEncrypted: welcome1
206+
```
207+
208+
One last note is that if the model or variables file contains encrypted passwords, add the `-use_encryption` flag to the command line to tell the Create Domain Tool that encryption is being used and to prompt for the encryption passphrase. As with the database passwords, the tool can also read the passphrase from standard input (for example, `stdin`) to allow the tool to run without any user input.
209+

‎site/deploy.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
## The Deploy Applications Tool
2+
3+
**NOTE: Work on the Deploy Applications Tool to bring it in line with the text below is still in progress.**
4+
5+
The Deploy Applications Tool uses a model, the archive, and WLST to deploy applications and resources into an existing WebLogic Server domain in either WLST online or offline mode. When deploying applications and resources from a model, the deploy tool focuses primarily on the `resources` and `appDeployments` sections of the model. There are exceptions for the `domainInfo` and `topology` sections, where those configuration elements are deemed to be "application-related." For example, the servers' `ServerStart` folder has an `Arguments` and a `ClassPath` attribute that change the server environment (when started by the Node Manager) that applications may rely on to function properly. Likewise, the `domainInfo` section contains a list of JAR files that are to be placed in `<DOMAIN_HOME>/lib` which are relevant to applications for a similar reason.
6+
7+
The Deploy Applications Tool will only add or update elements in the specified model. It will not attempt to remove any missing elements that were present in a previous model.
8+
9+
In WLST online mode, the tool tries to minimize the need to redeploy the applications and shared libraries, and the need to restart the server. It does this in a few ways:
10+
11+
- If the model references an application or shared library that is already deployed, the tool compares the binaries to determine whether redeployment is required. Redeployment of shared libraries is particularly expensive since all applications using the shared library must be redeployed--even if the application has not changed.
12+
- It looks at the knowledge base to determine which attributes require restart when they are changed. If an attribute requires restart, the tool compares the current and model values to make sure that they are different before trying to apply a change.
13+
14+
The goal is to make the tool both able to support iterative deployment and able to minimize service disruption while doing its work when working against a running domain.
15+
16+
Running the Deploy Applications Tool in WLST offline mode is very similar to running the Create Domain Tool; simply provide the domain location and archive file, and separate model and variable files, if needed. For example:
17+
18+
weblogic-deploy\bin\deployApps.cmd -oracle_home c:\wls12213 -domain_home domains\DemoDomain -archive_file DemoDomain.zip -model_file DemoDomain.yaml -variable_file DemoDomain.properties
19+
20+
In WLST online mode, simply replace the `-domain_home` argument with the information on how to connect to the WebLogic Server Administration Server, for example:
21+
22+
weblogic-deploy\bin\deployApps.cmd -oracle_home c:\wls12213 -domain_home domains\DemoDomain -archive_file DemoDomain.zip -model_file DemoDomain.yaml -variable_file DemoDomain.properties -admin_url t3://127.0.0.1:7001 -admin_user weblogic
23+
24+
As usual, the tool will prompt for the password (it can also be supplied by piping it to standard input of the tool).
25+
26+
When running the tool in WLST online mode, the deploy operation may require server restarts or a domain restart to pick up the changes. The deploy operation can also encounter situations where it cannot complete its operation until the domain is restarted. To communicate these conditions to scripts that may be calling the Deploy Applications Tool, the shell scripts have three special, non-zero exit codes to communicate these states:
27+
28+
- `101` - The domain needs to be restarted and the Deploy Applications Tool needs to be re-invoked with the same arguments.
29+
- `102` - The servers impacted by the deploy operation need to be restarted, in a rolling fashion, starting with the Administration Server, if applicable.
30+
- `103` - The entire domain needs to be restarted.
31+

‎site/discover.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## The Discover Domain Tool
2+
3+
The Discover Domain Tool provides a bootstrapping mechanism to creating a model and archive file by inspecting an existing domain and gathering configuration and binaries from it. Note that the model file produced by the tool is not directly usable by the Create Domain Tool or the Deploy Applications Tool because the Discover Domain Tool does not discover the passwords from the existing domain. Instead, it puts a `--FIX ME--` placeholder for passwords it finds. Domain users are also not discoverable so the tool does not create the `AdminUserName` and `AdminPassword` fields in the `domainInfo` section, which are needed by the Create Domain Tool. The idea of this tool is simply to provide a starting point where the user can edit the generated model and archive file to suit their needs for running one of the other tools.
4+
5+
To run the Discover Domain Tool, simply provide the domain location and the name of the archive file; a separate model file can also be provided to make editing the generated model easier. For example:
6+
7+
weblogic-deploy\bin\discoverDomain.cmd -oracle_home c:\wls12213 -domain_home domains\DemoDomain -archive_file DiscoveredDemoDomain.zip -model_file DiscoveredDemoDomain.yaml
8+
9+
When creating the archive, the tool will try to gather all binaries, scripts, and required directories referenced by the domain configuration with the following caveats.
10+
11+
1. Any binaries referenced from the `ORACLE_HOME` will not be gathered, as they are assumed to exist in any target domain to which model-driven operations will be applied. Doing this is key to allowing the model to be WebLogic Server version independent.
12+
2. In its current form, the discover domain Tool will only gather binaries and scripts that are accessible from the local machine. Warnings will be generated for any binaries or scripts that cannot be found but the configuration for those binaries will still be collected, where possible. It is the user's responsibility to add those missing files to the archive in the appropriate locations and edit the the model, as needed, to point to those files inside the archive using the relative path inside the archive (for example, `wlsdeploy/applications/myapp.ear`).
13+

0 commit comments

Comments
 (0)