Merge remote-tracking branch 'upstream/master'

cxharris · cxharris · commit 14bd8338cbb0 · 2019-05-13T10:33:23.000+01:00
diff --git a/docs/pages/cdp/cdp-Create-Zowe-CLI-profiles.md b/docs/pages/cdp/cdp-Create-Zowe-CLI-profiles.md
@@ -10,44 +10,62 @@ folder: cdp
 
 ### Step 1: Create a z/OSMF profile
 
-This profile identifies the z/OSMF server that has access to the directory on z/OS into which the CICS bundle will be deployed. You need to know the following from your z/OS system administrator:
+This profile defines the parameters needed to connect to the z/OSMF server on z/OS. You need to know the following from your z/OS system administrator:
 
-* *hostname* of the z/OSMF server.
-* *port number* of the z/OSMF server.
-* *user ID* and *password* to identify yourself to the z/OSMF server.
+| Option | Description |
+| --- | --- |
+| host | Host name of the z/OSMF server. |
+| port | Port number of the z/OSMF server. |
+| user | User ID to identify yourself to the z/OSMF server. |
+| password | Password to identify yourself to the z/OSMF server. |
+
+**Note**: The user ID needs to have sufficient permissions to remove and create directories and files in the directory specified by `--targetdir` in the cics-deploy profile. The user ID also needs permission to submit JCL and to run the DFHDPLOY utility as described in the **Security** heading in topic [Automate the deployment and undeployment of CICS bundles and applications with the DFHDPLOY utility](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.5.0/applications/deploying/dfhdploy_overview.html).
 
 For example, to create a z/OSMF profile:
+
 ```console
 zowe profiles create zosmf-profile myzos --host myzos.example.com --port 3000 --user myuserid --password mypassword --reject-unauthorized false --overwrite
 ```
+
 For help on using the options:
+
 ```console
 zowe profiles create zosmf-profile --help
 ```
+
 To test the connection to the z/OSMF server using the profile:
+
 ```console
 zowe zosmf check status
 ```
 
 ### Step 2: Create an SSH profile
 
-This profile defines the parameters needed to connect. to the remote SSH server. You need to know the following from your z/OS system administrator:
+This profile defines the parameters needed to connect to the SSH server on z/OS. You need to know the following from your z/OS system administrator:
 
-* *hostname* of the SSH server.
-* *port number* of the SSH server. This will default to 22.
-* *user ID* and *password* to identify yourself to the SSH server.
+| Option | Description |
+| --- | --- |
+| host | Host name of the SSH server. |
+| port | Port number of the SSH server. This will default to 22. |
+| user | User ID to identify yourself to the SSH server. |
+| password | Password to identify yourself to the SSH server. |
 
-It is recommended that you use the same user ID and host to connect with SSH as is used in the z/OSMF profile, failure to do so results in undefined behaviour.
+**Note**: It is recommended that you use the same user ID and host name to connect with SSH as is used in the z/OSMF profile, failure to do so results in undefined behaviour. When an SSH connection is made, the user's remote [z/OS shell .profile](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxa400/cupro.htm) is used to set-up the shell environment and variables. This remote .profile should include any necessary environment variables and npm configuration required to run `npm install`. This is descibed in [Installing and configuring](https://www.ibm.com/support/knowledgecenter/SSTRRS_6.0.0/com.ibm.nodejs.zos.v6.doc/install.htm).
 
 For example, to create an SSH profile:
+
 ```console
 zowe profiles create ssh-profile myzos --host myzos.example.com --user myuserid --password mypassword --overwrite
 ```
+
 For help on using the options:
+
 ```console
 zowe profiles create ssh-profile --help
 ```
+
 To test the connection to the SSH server using the profile:
+
 ```console
 zowe zos-uss issue ssh 'uname -a'
 ```
@@ -56,17 +74,27 @@ zowe zos-uss issue ssh 'uname -a'
 
 This profile identifies the CICS environment for deployment. You need to know the following from your CICS system administrator:
 
-* *CPSM CICSplex name*.
-* *High Level Qualifier* \(HLQ\) for the CICS and CPSM data sets.
-* *CPSM scope* to identify the CICS region or group of regions to deploy your application.
-* Optional - *CICS CSD group name or CPSM BAS resource group name* into which the bundle is defined.
-* Optional - *JCL jobcard* to use when submitting JCL that will run the CICS utility DFHDPLOY.
+| Option | Description |
+| --- | --- |
+| cicsplex | CPSM CICSplex name. |
+| cicshlq | High Level Qualifier \(HLQ\) for the CICS data sets. |
+| cpsmhlq | High Level Qualifier \(HLQ\) for the CPSM data sets. |
+| scope | CPSM scope to identify the CICS region or group of regions to deploy your application. |
+| resgroup or basgroup | CICS CSD group name or BAS resource group name into which the bundle is defined. If not specified, BUNDLE resources are defined in CPSM BAS for installation and then removed. |
+| jobcard | JCL jobcard to use when submitting JCL that will run the CICS utility DFHDPLOY. If not specified, a default jobcard will be used. |
+| targetdir | Target directory on z/OS to which CICS bundles should be uploaded. |
 
 For example to create a cics-deploy profile:
+
 ```console
-zowe profiles create cics-deploy-profile example --cicsplex PLEX1 --cicshlq CICSTS55.CICS720 --cpsmhlq CICSTS55.CPSM550 --scope TESTGRP1 --csdgroup BUNDGRP1 --overwrite
+zowe profiles create cics-deploy-profile example --cicsplex PLEX1 --cicshlq CICSTS55.CICS720 --cpsmhlq CICSTS55.CPSM550 --scope TESTGRP1 --csdgroup BUNDGRP1 --targetdir /var/cicsts/bundles
+--overwrite
 ```
+
 For help on using the options:
+
 ```console
 zowe profiles create cics-deploy-profile --help
-```
+```
+
+To test the cics-deploy profile, follow the steps in [Deploying your first app](cdp-Deploying-your-first-app).
diff --git a/docs/pages/cdp/cdp-Deploying-your-first-app.md b/docs/pages/cdp/cdp-Deploying-your-first-app.md
@@ -11,31 +11,59 @@ toc: false
 
 1. Install the Zowe CLI and cics-deploy plugin by following the steps in [Installation](cdp-Installation).
 
-1. Create Zowe CLI profiles for z/OSMF, SSH, and cics-deploy by following the steps in [Create Zowe CLI profiles](cdp-Create-Zowe-CLI-profiles).
+2. Create Zowe CLI profiles for z/OSMF, SSH, and cics-deploy by following the steps in [Create Zowe CLI profiles](cdp-Create-Zowe-CLI-profiles).
 
-1. Create a Node.js application.
+3. Create a Node.js application.
+
+   For example, to create a Node.js application using the [Express Application Generator](https://expressjs.com/en/starter/generator.html):
 
-   For example, to create a Node.js application using the Express Generator:
    ```console
    npm install -g express-generator
    express myExpressApp
    cd myExpressApp
    npm install
    npm start
    ```
-   The Node.js web server will start and you can browse to http://localhost:3000 to see the running application. Use CTRL+C to stop the Node.js web server.
 
-1. Package the Node.js application into a CICS bundle. The port needs to be available for use by the CICS region on z/OS.
+   The Node.js application will start. You can call the application from a browser using URL [http://localhost:3000/](http://localhost:3000/), and press CTRL+C to stop it.
 
-   ```console
-   zowe cics-deploy generate bundle --startscript app.js --port 3000 --overwrite
-   ```
+4. Package the Node.js application into a CICS bundle.
 
-1. Deploy the CICS bundle into CICS. Replace the value for `--targetdir` with a directory on z/OS that your user ID has write access to, and the CICS region user ID has read access to. 
+    Make sure you are in the root directory of the application. Replace the value for `--port` with one that is available for use by the CICS region on z/OS.
 
    ```console
-   zowe cics-deploy push bundle --name myExpressApp --targetdir /u/userid/bundles --overwrite
+    zowe cics-deploy generate bundle --port 3000 --overwrite
    ```
 
+    The output will show the directories and files created to form a CICS bundle:
+
+    ```console
+    define : NODEJSAPP "myexpressapp" with startscript "./bin/www"
+    create : nodejsapps
+    create : nodejsapps/myexpressapp.nodejsapp
+    create : nodejsapps/myexpressapp.profile
+    create : .zosattributes
+    create : META-INF
+    create : META-INF/cics.xml
+    CICS Bundle generated with bundleid "myexpressapp"
+    ```
+
+5. Deploy the CICS bundle into CICS.
+
+    Replace the value for `--name` with the name of the BUNDLE resource to be created in CICS.
+
+    ```console
+    zowe cics-deploy push bundle --name Express --overwrite
+    ```
+
+    A progress bar is shown and updated as the CICS bundle is deployed and the application is started. This can take a few minutes. If there are errors, retry with the `--verbose` option for more detailed output.
+
+6. Test the Node.js application.
+
+    You can call the application from a browser using URL [http://myzos:3000/](http://myzos:3000/), replacing _myzos_ with the host name of the z/OS system, and _3000_ with the port specified in step 4.
+
+    You can make changes to the application and redeploy it by repeating step 5.
+
 ### Results
-The Node.js web server will start and you can browse to http://myzos:3000 to see the running application.
+
+The Node.js application is packaged into a CICS bundle on the workstation, uploaded to a directory on z/OS, and is running in CICS.
diff --git a/docs/pages/cdp/cdp-Home.md b/docs/pages/cdp/cdp-Home.md
@@ -13,7 +13,7 @@ It aims to provide an experience for developers and CI/CD automation pipelines s
 The plug-in provides the following commands:
 * [zowe cics-deploy generate bundle]({{ site.path_to_generated_docs }}CLIReadme.md#module-generate) - Generate a CICS bundle in the working directory. Typically used by developers to package their existing application as a CICS bundle.
 
-* [zowe cics-deploy push bundle]({{ site.path_to_generated_docs }}CLIReadme.md#module-push) - Firstly undeploy the previous version of the CICS bundle from CICS incase it was been previously deployed. Then copy the bundle from the working directory to a z/OS directory, and run npm to install dependencies for each Node.js application in the bundle. Finally deploy the bundle to one or more CICS regions within a CICSplex. Typically used by developers to deploy applications in CICS ready for testing.
+* [zowe cics-deploy push bundle]({{ site.path_to_generated_docs }}CLIReadme.md#module-push) - Firstly undeploy the previous version of the CICS bundle from CICS incase it had been previously deployed. Then copy the bundle from the working directory to a z/OS directory, and run npm to install dependencies for each Node.js application in the bundle. Finally deploy the bundle to one or more CICS regions within a CICSplex. Typically used by developers to deploy applications in CICS ready for testing.
 
 * [zowe cics-deploy deploy bundle]({{ site.path_to_generated_docs }}CLIReadme.md#module-deploy) - Deploy a CICS bundle that is in a z/OS directory to one more CICS regions within a CICSplex. The DFHDPLOY utility is used to define the BUNDLE resource in a CICS system definition (CSD) file or CPSM Business Application Services (BAS) file, then install and enable the resource in the target CICS regions. Typically used by developers and CI-CD pipelines that require more precise control when deploying applications to CICS, for example to install the bundle in subsets of CICS regions in a cluster in a manner that maintains the availability of the application for clients.
 
diff --git a/docs/pages/cdp/cdp-Installation.md b/docs/pages/cdp/cdp-Installation.md
@@ -6,25 +6,30 @@ summary: "To install the Zowe CLI and cics-deploy plugin, perform the following
 sidebar: cdp_sidebar
 permalink: cdp-Installation.html
 folder: cdp
+toc: false
 ---
 
 1. Install [Node.js V8.0](https://nodejs.org/en/download/) or later, and Node Package Manager (npm) V5.0 or later, that are required by Zowe CLI. To verify the versions installed:
+
    ```console
    node --version
    npm --version
    ```
 
 2. Install [Zowe CLI](https://zowe.github.io/docs-site/latest/user-guide/cli-installcli.html). For example to install using npm:
+
    ```console
    npm install -g zowe-cli
    ```
 
 3. Install the cics-deploy plugin:
+
    ```console
    zowe plugins install zowe-cli-cics-deploy-plugin
    ```
 
 4. Verify the version of the plugin that is installed:
+
    ```console
    zowe plugins list
    ```
diff --git a/docs/pages/cdp/cdp-Requirements.md b/docs/pages/cdp/cdp-Requirements.md
@@ -6,17 +6,21 @@ summary: "The cics-deploy plugin is dependent on several servers and facilities
 sidebar: cdp_sidebar
 permalink: cdp-Requirements.html
 folder: cdp
+toc: false
 ---
 
 ### z/OS Management Facility
+
 A [z/OS Management Facility (z/OSMF)](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.izua300/IZUHPINFO_PartConfiguring.htm) server is required to run the [push bundle](Commands#command-push-bundle), [deploy bundle](Commands#command-deploy-bundle), and [undeploy bundle](Commands#command-undeploy-bundle) commands. These commands call the API for [`zowe zos-jobs submit`](https://zowe.github.io/docs-site/latest/user-guide/cli-usingcli.html#zos-jobs) to submit JCL that executes the DFHDPLOY utility to deploy and undeploy CICS bundles.
 
 The z/OSMF server is also required by the [push bundle](Commands#command-push-bundle) command when it uses the API for [`zowe files upload dir-to-uss`](https://github.com/zowe/zowe-cli/issues/207) to copy a CICS bundle to a z/OS directory.
 
 ### z/OS Secure SHell daemon
+
 The [z/OS Secure SHell daemon (sshd)](https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.3.0/com.ibm.zos.v2r3.foto100/sshset.htm) is required to run the [push bundle](Commands#command-push-bundle) command. This command uses the API for [`zowe zos-uss issue ssh`](https://github.com/zowe/zowe-cli/pull/308) to remove old files from the CICS bundle directory on z/OS and execute `npm install` on z/OS to install dependencies for Node.js applications.
 
 ### DFHDPLOY utility
+
 The [DFHDPLOY](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.5.0/applications/deploying/dfhdploy_overview.html) utility is provided with IBM CICS Transaction Server (CICS) and is required to run the [push bundle](Commands#command-push-bundle), [deploy bundle](Commands#command-deploy-bundle), and [undeploy bundle](Commands#command-undeploy-bundle) commands. These commands start DFHDPLOY with a script to perform deploy and undeploy operations. For example the deploy operation will define, install, then enable a CICS BUNDLE resource in a one or more CICS regions.
 
 The DFHDPLOY utility requires CICSPlex System Manager \(CPSM\) that is also provided with CICS to be configured, and for CPSM to be connected to the target CICS regions.
