Merge pull request #177 from markcocker/master

Update tutorial to focus on deploying Node.js apps

Author: tasha-m-k

docs/_data/sidebars/cdp_sidebar.yml

@@ -24,14 +24,14 @@ entries:
   - title: Tutorials
     output: web
     folderitems:
-    - title: Deploying your first app
-      url: /cdp-Deploying-your-first-app.html
+    - title: Deploying your first Node.js app
+      url: /cdp-Deploying-your-first-nodejs-app.html
       output: web
     - title: Deploying using individual actions
       url: /cdp-Deploying-using-individual-actions.html
       output: web
-    - title: Deploying into z/OS PT CICS region
-      url: /cdp-Deploying-into-zospt-cics-region.html
+    - title: Provision a CICS region using z/OS PT
+      url: /cdp-Provision-a-CICS-region-using-zospt.html
       output: web
 
   - title: Concepts
@@ -43,7 +43,7 @@ entries:
     - title: Zowe CLI profiles
       url: /cdp-zowe-profiles.html
       output: web
-    - title: CICS Bundles
+    - title: CICS bundles
       url: /cdp-cics-bundles.html
       output: web
 
@@ -73,7 +73,7 @@ entries:
       url: cdp-CLIReadMe#set-default--set
       output: web
 
-  - title: Commands - CICS deploy
+  - title: Commands - zowe cics-deploy
     output: web
     folderitems:
     - title: generate bundle

docs/_data/tags.yml

@@ -5,3 +5,4 @@ allowed-tags:
   - getting_started
   - concepts
   - troubleshooting
+  - tutorial

docs/pages/cdp/cdp-Create-Zowe-CLI-profiles.md

@@ -96,4 +96,4 @@ For help on using the options:
 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).
+To test the cics-deploy profile, follow the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).

docs/pages/cdp/cdp-Deploying-using-individual-actions.md

@@ -1,15 +1,15 @@
 ---
 title: Deploying using individual actions
-tags: [getting_started]
+tags: [tutorial]
 keywords:
 summary: "The following steps take you through the individual actions to deploy a Node.js application in CICS."
 sidebar: cdp_sidebar
 permalink: cdp-Deploying-using-individual-actions.html
 folder: cdp
-toc: false
+toc: true
 ---
 
-The `zowe cics-deploy push bundle` command performs a set of actions to deploy applications to CICS, as can be seen in [Deploying your first app](cdp-cdp-Deploying-your-first-app). The main actions include:
+The `zowe cics-deploy push bundle` command performs a set of actions to deploy applications to CICS, as can be seen in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app). The main actions include:
 
 * undeploy the old version of the CICS bundle in CICS
 * upload the new version of the CICS bundle to z/OS

docs/pages/cdp/cdp-Deploying-your-first-app.md renamed to docs/pages/cdp/cdp-Deploying-your-first-nodejs-app.md

@@ -1,21 +1,25 @@
 ---
-title: Deploying your first app
-tags: [getting_started]
+title: Deploying your first Node.js app
+tags: [tutorial]
 keywords:
-summary: "The following steps take you through deploying your first Node.js application to CICS."
+summary: "The following steps take you through deploying your first Node.js application to CICS using the Express Application Generator."
 sidebar: cdp_sidebar
-permalink: cdp-Deploying-your-first-app.html
+permalink: cdp-Deploying-your-first-nodejs-app.html
 folder: cdp
-toc: false
+toc: true
 ---
 
+### Before you begin
+
+CICS TS V5.5 introduced support to run Node.js applications and is required by this tutorial. If you do not have a CICS TS V5.5 region, use the steps in [Provision a CICS region using z/OS PT](cdp-Provision-a-CICS-region-using-zospt) to provision one, or speak to your CICS system administrator.
+
+### Procedure
+
 1. Install the Zowe CLI and cics-deploy plugin by following the steps in [Installation](cdp-Installation).
 
 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).
 
-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):
+3. Create a Node.js application using the [Express Application Generator](https://expressjs.com/en/starter/generator.html):
 
    ```console
    npm install -g express-generator
@@ -29,45 +33,44 @@ toc: false
 
 4. Package the Node.js application into a [CICS bundle](cdp-cics-bundles).
 
-    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.
+    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. This sets the PORT environment variable in the generated `.profile` file. Additional variables can be set by editing this file.
 
    ```console
     zowe cics-deploy generate bundle --port 3000 --overwrite
    ```
 
     The output will show the directories and files created to form a CICS bundle. For example:
 
-    ```console
+    <pre class="messageText">
     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. Update the CICS Node.js application profile if your application requires environment variables to be set.
-
-    Edit the `.profile` file created in step 4, for example `nodejsapps/myexpressapp.profile`.
+    CICS Bundle generated with bundleid "myexpressapp"</pre>
 
-6. Deploy the CICS bundle into CICS.
-
-    Replace the value for `--name` with the name of the BUNDLE resource to be created in CICS.
+5. Deploy the CICS bundle into CICS.
 
     ```console
     zowe cics-deploy push bundle --name Express --overwrite
     ```
 
-    A progress bar is shown with status messages 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.
+    A progress bar is shown with status messages 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, or refer to [Troubleshooting](cdp-Troubleshooting-General).
+
+    This results in a CICS BUNDLE resource named `Express` to be created, installed and enabled in CICS. If the BUNDLE `Express` was already defined or installed in CICS, it is undeployed first. As the BUNDLE is enabled, the Node.js application is started.
 
 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 6.
+    If you make changes to the application you can redeploy it by repeating step 5.
 
 ### Results
 
-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.
+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.
+
+{% include tip.html content="[Best practice for developing Node.js applications](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.5.0/applications/developing/node/best-practice.html) provides guidance on setting and using environment variables and graceful application termination." %}

docs/pages/cdp/cdp-Home.md

@@ -2,21 +2,22 @@
 title: Zowe CLI CICS deploy plugin
 tags: [getting_started]
 keywords:
-summary: "The Zowe command line interface (CLI) provides a simple and streamlined way to interact with IBM z/OS. The cics-deploy plugin extends the Zowe CLI to deploy Node.js applications developed on a workstation to IBM CICS Transaction Server for z/OS (CICS)."
+summary: "The Zowe command line interface (CLI) provides a simple and streamlined way to interact with IBM z/OS. The cics-deploy plugin extends the Zowe CLI to deploy applications developed on a workstation to IBM CICS Transaction Server for z/OS (CICS)."
 sidebar: cdp_sidebar
 permalink: index.html
 folder: cdp
 ---
 
-It provides a Node.js CICS deployment workflow for developers and CI/CD automation pipelines similar to that experienced when deploying Node.js applications to the cloud.
+It provides a CICS deployment workflow for developers and CI/CD automation pipelines similar to that experienced when deploying applications to cloud environments.
 
-Before you start, and especially if you are not familiar with the world of z/OS, Zowe and CICS, it's a good idea to read about some of the key concepts, which include [Zowe](cdp-zowe-and-cli), [Zowe CLI profiles](cdp-zowe-profiles) and [CICS bundles](cdp-cics-bundles). If you're keen to get going quickly, you can jump right in and follow along with our tutorial on [Deploying your first app](cdp-Deploying-your-first-app).
+Before you start, and especially if you are not familiar with the world of z/OS, Zowe and CICS, it's a good idea to read about some of the key concepts, which include [Zowe](cdp-zowe-and-cli), [Zowe CLI profiles](cdp-zowe-profiles) and [CICS bundles](cdp-cics-bundles). If you're keen to get going quickly, you can jump right in and follow along with our tutorial on [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).
 
-When everything has been [installed](cdp-Installation) and [you've created the Zowe CLI profiles](cdp-Create-Zowe-CLI-profiles), you can deploy a Node.js application from your workstation to CICS in two steps:
+When everything is [installed](cdp-Installation) and you have [created the Zowe CLI profiles](cdp-Create-Zowe-CLI-profiles), you can deploy an application from your workstation to CICS in two steps:
 
 1. Use the [zowe cics-deploy generate bundle](cdp-CLIReadMe#generate--g--gen) command to generate some metadata and artifacts that help the target CICS system understand your application.
-1. Use the [zowe cics-deploy push bundle](cdp-CLIReadMe#push--p) command to push the generated bundle to one or more regions within a CICSplex, enabling and deploying it as an executing application. 
+
+2. Use the [zowe cics-deploy push bundle](cdp-CLIReadMe#push--p) command to push the generated bundle to one or more regions within a CICSplex, enabling and deploying it as an executing application. 
 
 Should you need it, and if you understand a little more about CICS, further commands like [zowe cics-deploy deploy bundle](cdp-CLIReadMe#deploy--d--dep) and [zowe cics-deploy undeploy bundle](cdp-CLIReadMe#undeploy--u--udep) offer you finer-grained control of the process - for example, to enable you to install a bundle in subsets of CICS regions in a cluster in such a way as to maintain an application's availability for clients.
 
-If you hit any speed bumps on your journey, check out our [Troubleshooting](cdp-Troubleshooting-General) pages.
+If you hit any speed bumps on your journey, check out our [Troubleshooting](cdp-Troubleshooting-General) pages.

docs/pages/cdp/cdp-Deploying-into-zospt-cics-region.md renamed to docs/pages/cdp/cdp-Provision-a-CICS-region-using-zospt.md

@@ -1,10 +1,10 @@
 ---
-title: Provision a CICS region using z/OS PT and deploy a Node.js application
-tags: [getting_started]
+title: Provision a CICS region using z/OS PT
+tags: [tutorial]
 keywords:
-summary: "The following steps take you through provisioning a CICS region using the z/OS Provisioning Toolkit, then creating and deploying an application to the CICS region."
+summary: "The following steps take you through preparing a z/OS Provisioning Toolkit image for CICS, provisioning a CICS region using the image, and then starting, stopping and deprovisioning it."
 sidebar: cdp_sidebar
-permalink: cdp-Deploying-into-zospt-cics-region.html
+permalink: cdp-Provision-a-CICS-region-using-zospt.html
 folder: cdp
 toc: true
 ---
@@ -84,11 +84,7 @@ zospt build $ZOSPTIMAGE -t cics_55_nodejs
    zowe profiles update cics-deploy cics --scope CICPY000 --bundle-directory /u/cicprov/mnt/CICPY000/bundles
    ```
 
-4. Deploy your Node.js application to the CICS region using the steps in [Deploying your first app](cdp-Deploying-your-first-app). For example:
-
-   ```console
-   zowe cics-deploy push bundle --name Express --overwrite
-   ```
+You are now ready to deploy applications to the provisioned CICS region. You can try this out by following the steps in [Deploying your first Node.js app](cdp-Deploying-your-first-nodejs-app).
 
 ### Stop your CICS region