Merge pull request #48 from chirangaalwis/cf-is-patterns-readmes

Refine the README.md files

pattern-1/bosh-release/README.md

@@ -112,11 +112,10 @@ In order to create the BOSH release for deployment pattern 1, you must follow th
  Property | Description | Default
  -------- | ----------- | -------
  wso2is.user_ds.url | Connection URL of the user data source. | -
- wso2is.user_ds.driver | Database driver class name of the user data source. | -
  wso2is.registry_ds.url | Connection URL of the registry data source. | -
- wso2is.registry_ds.driver | Database driver class name of the registry data source. | -
  wso2is.identity_ds.url | Connection URL of the identity data source. | -
- wso2is.identity_ds.driver | Database driver class name of the identity data source. | -
+ wso2is.bps_ds.url | Connection URL of the BPS data source. | -
+ wso2is.db.driver | Database driver class name of the data source. | -
  wso2is.db.username | Username of the WSO2 Identity Server product database user. | root
  wso2is.db.password | Password of the WSO2 Identity Server product database user. | root
 

pattern-1/bosh-release/bosh-lite.md

@@ -99,11 +99,10 @@ for creating a release with BOSH.
  Property | Description | Default
  -------- | ----------- | -------
  wso2is.user_ds.url | Connection URL of the user data source. | -
- wso2is.user_ds.driver | Database driver class name of the user data source. | -
  wso2is.registry_ds.url | Connection URL of the registry data source. | -
- wso2is.registry_ds.driver | Database driver class name of the registry data source. | -
  wso2is.identity_ds.url | Connection URL of the identity data source. | -
- wso2is.identity_ds.driver | Database driver class name of the identity data source. | -
+ wso2is.bps_ds.url | Connection URL of the BPS data source. | -
+ wso2is.db.driver | Database driver class name of the data source. | -
  wso2is.db.username | Username of the WSO2 Identity Server product database user. | root
  wso2is.db.password | Password of the WSO2 Identity Server product database user. | root
 

pattern-1/bosh-release/jobs/wso2is_1/spec

@@ -16,16 +16,6 @@ packages:
 - wso2is
 
 properties:
- wso2is.memory.min_heap:
- description: Min Heap in MB
- default: 2048
- wso2is.memory.max_heap:
- description: Max Heap in MB
- default: 2048
- wso2is.memory.max_permgen:
- description: Max permgen in MB
- default: 1024
-
  wso2is.user_ds.url:
  description: Connection URL of the user data source
  wso2is.bps_ds.url:

pattern-1/bosh-release/jobs/wso2is_1/templates/ctl.erb

@@ -34,12 +34,6 @@ mkdir -p ${run_dir} ${log_dir}
 # provide ownership of the directories 'vcap' user and group
 chown -R vcap:vcap ${run_dir} ${log_dir}
 
-# set variables for your software
-min_heap=<%=properties.wso2is.memory.min_heap %>
-max_heap=<%=properties.wso2is.memory.max_heap %>
-max_permgen=<%=properties.wso2is.memory.max_permgen %>
-export JAVA_OPTS=" -Xmx${max_heap}m -Xms${min_heap}m -XX:MaxPermSize=${max_permgen}m"
-
 debug_log=${log_dir}/${wso2_product}.log
 touch ${debug_log}
 

pattern-1/bosh-release/jobs/wso2is_2/spec

@@ -16,16 +16,6 @@ packages:
 - wso2is
 
 properties:
- wso2is.memory.min_heap:
- description: Min Heap in MB
- default: 2048
- wso2is.memory.max_heap:
- description: Max Heap in MB
- default: 2048
- wso2is.memory.max_permgen:
- description: Max permgen in MB
- default: 1024
-
  wso2is.user_ds.url:
  description: Connection URL of the user data source
  wso2is.bps_ds.url:

pattern-1/bosh-release/jobs/wso2is_2/templates/ctl.erb

@@ -34,12 +34,6 @@ mkdir -p ${run_dir} ${log_dir}
 # provide ownership of the directories 'vcap' user and group
 chown -R vcap:vcap ${run_dir} ${log_dir}
 
-# set variables for your software
-min_heap=<%=properties.wso2is.memory.min_heap %>
-max_heap=<%=properties.wso2is.memory.max_heap %>
-max_permgen=<%=properties.wso2is.memory.max_permgen %>
-export JAVA_OPTS=" -Xmx${max_heap}m -Xms${min_heap}m -XX:MaxPermSize=${max_permgen}m"
-
 debug_log=${log_dir}/${wso2_product}.log
 touch ${debug_log}
 

pattern-2/bosh-release/README.md

@@ -1,13 +1,25 @@
 # BOSH release for WSO2 Identity Server deployment pattern 2
 
 This directory contains the BOSH release implementation for WSO2 Identity Server 5.4.0
-[deployment pattern 2](https://docs.wso2.com/display/IS541/Deployment+Patterns#DeploymentPatterns-Pattern2-HAclustereddeploymentofWSO2IdentityServerwithWSO2IdentityAnalytics).
+[deployment pattern 2](https://docs.wso2.com/display/IS540/Deployment+Patterns#DeploymentPatterns-Pattern2-HAclustereddeploymentofWSO2IdentityServerwithWSO2IdentityAnalytics).
 
 ![WSO2 Identity Server 5.4.0 deployment pattern 2](images/pattern-2.png)
 
-The following sections provide step-by-step guidelines for managing the WSO2 Identity Server 5.4.0 deployment pattern 2 BOSH release.
+The following sections provide general steps required for managing the WSO2 Identity Server 5.4.0 deployment pattern 2
+BOSH release in a BOSH environment deployed in the desired IaaS.
 
-For clarity, examples for the relevant steps have been provided for managing the BOSH release in a [BOSH Lite](https://bosh.io/docs/bosh-lite) environment.
+For step-by-step guidelines to manage the BOSH release in specific environments, refer the following:
+ - [In a local environment](bosh-lite.md) (using BOSH Lite)
+
+## Contents
+
+* [Prerequisites](#prerequisites)
+* [Create Release](#create-release)
+* [Deploy Release](#deploy-release)
+* [Output](#output)
+* [Delete Deployment](#delete-deployment)
+* [BOSH Release Structure](#bosh-release-structure)
+* [References](#references)
 
 ## Prerequisites
 
@@ -16,13 +28,15 @@ For clarity, examples for the relevant steps have been provided for managing the
  - [BOSH Command Line Interface (CLI) v2+](https://bosh.io/docs/cli-v2.html)
  - [WSO2 Update Manager (WUM)](http://wso2.com/wum)
  - [Git client](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+ - Software requirements specific to the IaaS
 
 2. Obtain the following software distributions.
 
  - WSO2 Identity Server 5.4.0 WUM updated product distribution
  - WSO2 Identity Server Analytics 5.4.0 WUM updated product distribution
  - [Java Development Kit (JDK) 1.8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
- - [MySQL JDBC driver](https://dev.mysql.com/downloads/connector/j/5.1.html)
+ - Relevant Java Database Connectivity (JDBC) connector (e.g. [MySQL JDBC driver](https://dev.mysql.com/downloads/connector/j/5.1.html)
+ if the external database used is MySQL)
 
 3. Clone this Git repository.
 
@@ -32,7 +46,7 @@ For clarity, examples for the relevant steps have been provided for managing the
 
  **Note**: In the remaining sections, the project root directory has been referred to as, **pivotal-cf-is**.
 
-## Create the BOSH Release
+## Create release
 
 In order to create the BOSH release for deployment pattern 2, you must follow the standard steps for creating a release with BOSH.
 
@@ -46,20 +60,14 @@ In order to create the BOSH release for deployment pattern 2, you must follow th
 
  Please refer the [BOSH documentation](http://bosh.io/docs/init.html) for instructions on creating a BOSH environment in the desired IaaS.
 
- **e.g.** Steps to create a BOSH environment with BOSH Lite as Director VM and login to it, can be found from
- [here](http://bosh.io/docs/bosh-lite.html#install).
-
- Once you setup the BOSH Lite environment, visit the VirtualBox application to confirm a new VM has been created.
-
- ![BOSH Lite VM](images/bosh-lite.png)
-
 3. Move back to the root directory of deployment pattern 2 BOSH release (`<pivotal-cf-is>/pattern-2/bosh-release`).
 
  ```
  cd ..
  ```
 
-4. Add the WSO2 Identity Server 5.4.0 and Identity Server Analytics 5.4.0 WUM updated product distributions, JDK distribution and MySQL JDBC driver in the form of release blobs.
+4. Add the WSO2 Identity Server 5.4.0 and Identity Server Analytics 5.4.0 WUM updated product distributions, JDK distribution and MySQL JDBC driver
+in the form of release blobs.
 
  Here, the **environment-alias** refers to the alias provided when saving the created environment, in step 2.
 
@@ -70,25 +78,11 @@ In order to create the BOSH release for deployment pattern 2, you must follow th
  bosh -e <environment-alias> add-blob <local_system_path_to_WSO2_IS_Analytics_distribution> wso2is_analytics/wso2is-analytics-<version>.zip
  ```
 
- **e.g.**
- Assuming that,
-
- - the created BOSH environment (with BOSH Lite as the Director) was saved with alias `vbox`, in step 2
- - the required binaries reside within `~/Downloads` directory
-
- ```
- bosh -e vbox add-blob ~/Downloads/jdk-8u144-linux-x64.tar.gz oraclejdk/jdk-8u144-linux-x64.tar.gz
- bosh -e vbox add-blob ~/Downloads/mysql-connector-java-5.1.34-bin.jar mysqldriver/mysql-connector-java-5.1.34-bin.jar
- bosh -e vbox add-blob ~/Downloads/wso2is-5.4.0.zip wso2is/wso2is-5.4.0.zip
- bosh -e vbox add-blob ~/Downloads/wso2is-analytics-5.4.0.zip wso2is_analytics/wso2is-analytics-5.4.0.zip
- ```
-
 5. **[Optional]** If the BOSH release is a final release, upload the blobs (added in step 4). Please refer
 [BOSH documentation](https://bosh.io/docs/create-release.html#upload-blobs) for further details.
 
- **e.g.**
  ```
- bosh -e vbox -n upload-blobs
+ bosh -e <environment-alias> -n upload-blobs
  ```
 
 6. Create the BOSH release.
@@ -105,34 +99,41 @@ In order to create the BOSH release for deployment pattern 2, you must follow th
  ```
  Please refer [BOSH Documentation](https://bosh.io/docs/create-release.html#final-release) for detailed information on creating a final release.
 
-## Deploy the BOSH Release
+## Deploy release
 
-1. Setup and configure external product MySQL database(s).
+1. Setup and configure external product database(s).
 
- - Following table shows the external product database configurations, which have been set as properties under WSO2 Identity Server and Analytics job specifications
+ - Currently, it is expected that the external database holds the user management, registry, identity and workflow feature database tables
+ for Identity Server and Identity Server Analytics.
+ Please see WSO2 Identity Server [Documentation](https://docs.wso2.com/display/IS540/Setting+Up+Separate+Databases+for+Clustering)
+ for further details.
+
+ - Following table shows the external product database configurations, which have been set as properties under WSO2 Identity Server job specifications
  (**e.g.** see `properties` section under `<pivotal-cf-is>/pattern-2/bosh-release/jobs/wso2is_<job_number>/spec`).
 
  <br>
 
  Property | Description | Default
  -------- | ----------- | -------
- wso2is.mysql.host | Hostname/IP of the MySQL server in which WSO2 Identity Server product database resides. | 192.168.50.1
- wso2is.mysql.product_db | Name of the WSO2 Identity Server product database. | wso2is_db
- wso2is.product_db.username | Username of the WSO2 Identity Server product database user. | root
- wso2is.product_db.password | Password of the WSO2 Identity Server product database user. | root
-
- If you customize any of the above configurations in following steps, change the default property values to customized values in each job specification.
-
- - Create the product database. For this purpose, execute the `<pivotal-cf-is>/pattern-2/bosh-release/dbscripts/mysql.sql` script.
-
- ```
- DROP DATABASE IF EXISTS <wso2is.mysql.product_db>; CREATE DATABASE <wso2is.mysql.product_db>;
- USE <wso2is.mysql.product_db>; SOURCE /dbscripts/mysql.sql;
- ```
+ wso2is.user_ds.url | Connection URL of the user data source. | -
+ wso2is.registry_ds.url | Connection URL of the registry data source. | -
+ wso2is.identity_ds.url | Connection URL of the identity data source. | -
+ wso2is.bps_ds.url | Connection URL of the BPS data source. | -
+ wso2is.db.driver | Database driver class name of the data source. | -
+ wso2is.db.username | Username of the WSO2 Identity Server product database user. | root
+ wso2is.db.password | Password of the WSO2 Identity Server product database user. | root
+ wso2is_analytics.user_ds.url | Connection URL of the user data source | -
+ wso2is_analytics.registry_ds.url | Connection URL of the Registry data source | -
+ wso2is_analytics.event_store_ds.url | Connection URL of the event store data source | -
+ wso2is_analytics.processed_data_store_ds.url | Connection URL of the processed data store data source | -
+ wso2is_analytics.db.username | Username of the WSO2 Identity Server Analytics product database user | root
+ wso2is_analytics.db.password | Password of the WSO2 Identity Server Analytics product database user | root
+
+ Among the above, the properties with no default values **must** be set in the deployment manifest,
+ prior deployment of the release.
+ If you intend to customize any of the properties with default values, you may set the customized values
+ in the deployment manifest, prior to deployment of the release.
 
- This will create the tables to hold user management data, identity related data and workflow feature data
- (see [Setting Up Separate Databases for Clustering](https://docs.wso2.com/display/IS541/Setting+Up+Separate+Databases+for+Clustering)).
-
 2. Move to the root directory of deployment pattern 2 BOSH release.
 
  ```
@@ -150,74 +151,55 @@ In order to create the BOSH release for deployment pattern 2, you must follow th
  ```
  bosh -e <environment-alias> upload-stemcell <URL/local_system_path_to_stemcell>
  ```
-
- **e.g.** When uploading the stemcell to BOSH Lite environment created in previous section (see example steps under section [Create the BOSH Release](#create-the-bosh-release)),
-
- ```
- bosh -e vbox upload-stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-trusty-go_agent
- ```
 
 5. Upload the deployment manifest.
 
  ```
- bosh -e <environment-alias> -d wso2is-pattern-2 deploy manifests/wso2is-manifest.yml
- ```
-
- **e.g.** Uploading the deployment manifest to BOSH Lite environment
-
- ```
- bosh -e vbox -d wso2is-pattern-2 deploy manifests/wso2is-manifest.yml
+ bosh -e <environment-alias> -d wso2is-pattern-2 deploy manifests/<deployment-manifest>.yml
  ```
 
 ## Output
 
-To find the IP addresses of created instances via the BOSH CLI and access the WSO2 Identity Server and Analytics management consoles via a web browser,
+To find the IP addresses of created instances via the BOSH CLI and access the WSO2 Identity Server management console via a web browser,
 
 1. List all the instances within a deployment.
 
  ```
  bosh -e <environment-alias> -d wso2is-pattern-2 vms
  ```
-
- **e.g.** To find the deployed job instances within the deployment in BOSH Lite,
- ```
- bosh -e vbox -d wso2is-pattern-2 vms
- ```
-
- ![Job instances](images/output.png)
 
 2. SSH into an instance.
 
  ```
  bosh -e <environment-alias> -d wso2is-pattern-2 ssh <instance_id>
  ```
 
- **e.g.** `bosh -e vbox -d wso2is-pattern-2 ssh wso2is_1/7c3c2498-d9ed-4b58-ad18-85d2c6215311`
-
-3. Access the WSO2 Identity Server management console URL.
+3. Access the WSO2 Identity Server management console URL using the static IPs of the created instances.
 
  ```
- https://10.244.15.2:9443/carbon/
+ https://<IP_Address_of_IS_instance_1>:9443/carbon
+ ```
+ or
+ ```
+ https://<IP_Address_of_IS_instance_2>:9443/carbon
  ```
-4. Access the WSO2 Identity Server Analytics management console URL.
+4. Access the WSO2 Identity Server Analytics management console URL using the static IPs of the created instances.
 
  ```
- https://10.244.15.4:9444/carbon/
+ https://<IP_Address_of_IS_Analytics_instance_1>:9444/carbon
+ ```
+ or
+ ```
+ https://<IP_Address_of_IS_Analytics_instance_2>:9444/carbon
  ```
 
-## Delete the BOSH release deployment
+## Delete deployment
 
 1. Delete the deployment.
 
  ```
  bosh -e <environment-alias> -d wso2is-pattern-2 delete-deployment
  ```
-
- **e.g.** To delete the WSO2 Identity Server pattern 2 deployment in the BOSH Lite environment,
-
- ```
- bosh -e vbox -d wso2is-pattern-2 delete-deployment
- ```
 
 2. **[Optional]** Cleanup the BOSH release, stemcell, disks and etc.
 
@@ -239,11 +221,9 @@ Structure of the directories and files of the BOSH release is as follows:
  ├── manifests
  ├── wso2is-manifest.yml
  ├── packages
- ├── README.md
+ └── README.md
 ```
 
 ## References
 
 * [BOSH CLI v2 commands](https://bosh.io/docs/cli-v2.html)
-* [A Guide to Using BOSH](http://mariash.github.io/learn-bosh/)
-* [BOSH Lite](https://bosh.io/docs/bosh-lite.html)