Merge lp:~mbruzek/charms/trusty/was-nd/readme-update into lp:~ibmcharmers/charms/trusty/was-nd/trunk

[Matt Bruzek]

While reviewing this charm I saw a few markdown errors and added the sections that I think are critical for users to understand.

Please consider adding this content to the original readme and improve on it where possible.

Unmerged revisions

14. By Matt Bruzek on 2015-08-28

Fixed markdown errors and added more critical information.

=== modified file 'README.md'
--- README.md	2015-07-24 11:50:42 +0000
+++ README.md	2015-08-28 22:31:21 +0000
@@ -1,71 +1,124 @@
 # Overview
 
-WebSphere Application Server Network Deployment 
+WebSphere Application Server Network Deployment
 
-IBM WebSphere Application Server Network Deployment provides an advanced, flexible runtime environment for large-scale application deployments. It offers near-continuous availability with advanced performance and management capabilities for mission-critical applications. For details on IBM Websphere Application Server Network Deployment please visit [here][WAS-ND-product-page].
+IBM WebSphere Application Server Network Deployment (WAS ND) provides an
+advanced, flexible runtime environment for large-scale application deployments.
+It offers near-continuous availability with advanced performance and management
+capabilities for mission-critical applications. For details on IBM WebSphere
+Application Server Network Deployment please visit [here][WAS-ND-product-page].
 
 # Usage
-Download your licensed IBM Installation Manager software version 1.5 and above for 'x86_64' based machine. And version 1.8 and above for 'ppc64le' based machine and upload to your apache repository. 
-
-Download your licensed IBM Websphere ND software 8.5.5.0 version and upload to your apache repository.
-
-Download your licensed IBM Websphere ND software WAS fixpack version 8.5.5.4 and upload to your apache repository.
-
-For 'ppc64le' based machines, Download your licensed IBM Websphere Base software WAS fixpack version 8.5.5.6 and upload to your apache repository.
-
-Put up all the downloaded contents on the web server like Apache and configure apache to serve these packages. These packages can be accessed using a URL from the web server.
-
-
-#Creating the repositories in Apache
-
-Run steps below with admin access
-
-Install needed packages
+> Please note this charm is not self-contained and requires additional software
+> to install.  You must download the IBM Installation Manager, IBM WebSphere
+> Network Deployment software, and host those files on an HTTP server that is accessible to the
+> Juju network to successfully deploy this charm.
+
+## Download the software
+
+Download the licensed IBM Installation Manager software version 1.5 and above
+for deployments to 'x86_64' based machines. Version 1.8 and above is required
+for 'ppc64le' based machines.  You must upload or host the zip file on an HTTP
+server such as Apache.
+
+Download the licensed IBM WebSphere ND software 8.5.5.0 version and upload
+all three parts to an HTTP server.
+
+Download the licensed IBM WebSphere ND software WAS fixpack version 8.5.5.4 and
+upload the two parts to an HTTP server.
+
+For 'ppc64le' based machines, Download your licensed IBM WebSphere Base
+software WAS fixpack version 8.5.5.6 and upload to your HTTP server.
+
+Put up all the downloaded content in the same directory on the HTTP server and
+configure the server to host these packages. Ensure these packages can be
+accessed using a URL from the web server before deploying the charm.
+
+The resulting HTTP directory should contain content similar to this:
+```
+8.5.5-WS-WAS-FP0000004-part1.zip
+8.5.5-WS-WAS-FP0000004-part2.zip
+Install_Mgr_v1.6.2_Lnx_WASv8.5.5.zip
+WASND_v8.5.5_1of3.zip
+WASND_v8.5.5_2of3.zip
+WASND_v8.5.5_3of3.zip
+```
+
+## Configure an HTTP to host the files
+
+To create an HTTP server such as Apache, perform the following steps with
+administrator access to a system.
+
+Install the HTTP software:  
+
     apt-get install dpkg-dev apache2
 
-Create the repository on apache server Under your apache repository directory.
-Configure apache server to allow access to the repository.
-
-To install the downloaded binaries you must agree to the IBM license. You can view the full license for IBM Installation Manager and IBM WebSphere Application Server Base by visiting the [Software license agreements search website][License] Search for "IBM Installation Manager" and "IBM Websphere Application Server" and choose the license that applies to the version you are using.
-
+Upload all the IBM software to the same directory of the Apache server.
+[Configure][Configure-Apache] the Apache server to allow access to the
+directory.  The `DocumentRoot` directive specifies where on the filesystem you
+should place these files.
+
+> To install the downloaded binaries you must agree to the IBM license for
+> each product. You can view the full license for IBM Installation Manager and
+> IBM WebSphere Application Server Base by visiting the
+> [Software license agreements search website][License]. Search for
+> "IBM Installation Manager" and "IBM WebSphere Application Server" and choose
+> the license that applies to the version you are using.
+
+## Deploy
+
+> Note: A full WebSphere Application Server Network Deployment installation
+> requires a minimum 16GB of disk space! It depends on the cloud provider, but
+> the default machines that Juju provisions may not have enough `root-disk`
+> to depoly was-nd successfully. You can use
+> `juju set-constraints root-disk=30G` or the `--constraints` flag on the
+> `juju deploy` command to change this property.  Read more about
+> [Juju Constraints][Juju-Constraints] to tune the size of instances.
 
 Run the following to deploy this charm:
 
     juju deploy was-nd
 
-At this point the charm will wait until the user accepts the license.  If you 
-agree to the license, run the following command:
-
-If the was_nd_url and im_filename is configured in the config.yaml:
+At this point the charm will wait until the user accepts the IBM software
+licenses.  If you agree to the licenses, set the configuration values to `True`:
 
     juju set was-nd accept-ibm-im-license=True accept-ibm-was-nd-license=True
 
-If not,
-
-    juju set was-nd accept-ibm-im-license=True accept-ibm-was-nd-license=True was_nd_url=<Web server URL> im_file_name=<IM package name> im_install_path=<IM Installation Path>
-
-
-You can then browse to "http://was-nd unit's ip-address:9060/ibm/console" to view WAS Console.
+Then set was_nd_url to the URL that the HTTP server is hosting the IBM software:
+
+    juju set was-nd was_nd_url=<Web server URL>
+
+You can optionally configure the IBM Installation Manager file name and install
+path if needed:
+
+    juju set im_file_name=<IM package name> im_install_path=<IM Installation Path>
+
+At this point the charm will deploy and this part may take some time.  To view
+the WebSphere Integrated Solutions Console on public clouds you need to expose
+the service with the command:
+
+    juju expose was-nd
+
+You can browse to "http://was-nd-ip-address:9060/ibm/console" to view the
+WebSphere Integrated Solutions Console.  You can get the unit ip address by
+running the command `juju status was-nd`
 
 # Configuration
 
-`accept-ibm-im-license`  
+`accept-ibm-im-license`
 The IBM Installation Manager software comes with special terms and conditions from IBM.
-The IBM Installation Manager software can only be used by accepting the terms and 
+The IBM Installation Manager software can only be used by accepting the terms and
 conditions found in the IBM-Installation-Manager-license.txt file.  
 
-Setting this option to True indicates that you have read and accept the 
+Setting this option to True indicates that you have read and accept the
 IBM  Installation Manager terms and conditions found in the license file.  
-The license file(s) can be found in the product binaries you downloaded. 
+The license file(s) can be found in the product binaries you downloaded.
 
 `accept-ibm-was-nd-license`
 Before you can use, extract, or install IBM WebSphere Application Server
 for Developers V8.5.5, you must accept the terms of International License
 Agreement for Non-Warranted Programs and additional license information.
-Please read the license agreement carefully.
-
-The license file can be found in the root directory of the charm source
-in the IBM-WebSphere-license.txt file
+Please read the license agreement carefully
 
 **The WebSphere software cannot be installed until the terms and
 contions are accepted.  The charm will not function correctly until the
@@ -85,39 +138,52 @@
 
 #IBM WAS ND Information
 
-(1) General Information 
-Information on IBM WAS ND available [here] [WAS-ND-Infocenter]
-
-(2) Download Information
-
-Downloadable Package Names for 'x86_64' based machine:
+General Information on IBM WAS ND available [here] [WAS-ND-Infocenter]
+
+### Download Information
+
+Downloadable package names for IBM WAS ND on 'x86_64' based machines:  
+```
 WASND_v8.5.5_1of3.zip
 WASND_v8.5.5_2of3.zip
 WASND_v8.5.5_3of3.zip
 8.5.5-WS-WAS-FP0000004-part1.zip
 8.5.5-WS-WAS-FP0000004-part2.zip
+```
 
-Downloadable Package Names for 'ppc64le' based machine:
+Downloadable package names for IBM WAS ND on 'ppc64le' based machines:  
+```
 WAS_ND_V8.5.5_FOR_POWERLE_ML.zip
 WASND_V8.5.5_2OF_2_FOR_POWERLE_ML.zip
 8.5.5-WS-WAS-LE-FP0000006-part1.zip
 8.5.5-WS-WAS-LE-FP0000006-part2.zip
-
-Information on procuring WAS product is available at the [Passport Advantage Site] [Passport-Advantage]
-
-Details about WAS ND 8.5.5.0 download available [here] [WAS-ND-8.5.5.0-download]
-
-Details about WAS 8.5.5.4 fixpack download available [here] [[WAS-ND-8.5.5.4-fixpack-download]
-
-A trial version is available [here] [WAS-ND-trail-version].
+```
+
+Downloadable package names for the IBM Installation Manager:  
+```
+Install_Mgr_v1.6.2_Lnx_WASv8.5.5.zip
+```
+
+Information on procuring WAS product is available at the
+[Passport Advantage Site][Passport-Advantage]
+
+Details about WAS ND 8.5.5.0 download available [here][WAS-ND-8.5.5.0-download]
+
+Details about WAS 8.5.5.4 fixpack download available [here][WAS-ND-8.5.5.4-fixpack-download]
+
+A trial version of the WAS ND software is available [here][WAS-ND-trail-version].
 
 More information about IBM IM Downloadable file available [here][IBM-IM-more-info]
 
-(3) Contact Information
+### Contact Information
 
-For issues with this charm, please contact [e-mail].
+For issues with this charm, please contact the IBM Juju Support team at
+<[e-mail]>.
 
 <!-- Links -->
+[Juju-Constraints]: https://jujucharms.com/docs/devel/charms-constraints
+
+[Configure-Apache]: http://httpd.apache.org/docs/2.4/getting-started.html
 
 [WAS-ND-Infocenter]: http://www-01.ibm.com/support/knowledgecenter/SSAW57_8.5.5/as_ditamaps/was855_welcome_ndmp.html?lang=en
 
@@ -138,4 +204,3 @@
 [WAS-ppc64le-fixpack-info]: http://www-01.ibm.com/support/docview.wss?uid=swg24040035
 
 [License]: http://www-03.ibm.com/software/sla/sladb.nsf/search
-