Get started with the Zowe WebUi, Part 1

This tutorial will consist of two parts:

Learning objectives

Here you will start by getting access to the mainframe with a pre-installed Zowe instance. After that, you will download the source from GitHub, and then build and run a local instance of zLUX on your local machine. You will also learn how to configure ZSS authentication, so you can use your mainframe credentials for login.

To request features or report bugs, please use the issues page in the zLUX repo with the dev-tutorial tag.

Prerequisites

Register to get username and password via email

Before you start the tutorial, please navigate to https://www-01.ibm.com/events/wwe/ast/mtm/zowe.nsf/enrollall?openform and register a username and password to access the mainframe. You will need this to login to your system and complete the tutorial.

Reset password

Sign up to join Open Mainframe Slack and follow the steps listed here to reset the password. We have installed the ZIH app in OMP slack which is our automated password reset agent.

Verify access to the mainframe

After you receive your login information, there are various ways to access the mainframe using credentials:

  1. Access z/OS using a TN3270 Emulator IP: 192.86.32.67 & PORT: 23.

     logon <username>
    

    If you have any access issues, this method provides descriptive information directly from RACF.

  2. Access z/OS using an SSH client (PuTTY or GitBash for windows) using your credentials.

     ssh <username>@192.86.32.67
    
  3. Access it using a browser via Zowe Desktop. Navigate to the URL https://192.86.32.67:8544/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html
    and use the same mainframe credentials as above to login.

  4. Access it using the Zowe CLI.

    • Install the Zowe CLI:

      npm i -g @zowe/cli@latest --ignore-scripts
      
    • Create the Zowe zosmf profile:

      zowe profiles create zosmf-profile --help
      zowe profiles create zosmf-profile zowe-tutorial --host 192.86.32.67 --port 10443 --user <username> --password <your-password> --reject-unauthorized false
      
    • Verify Zowe access:

      zowe zosmf check status
      
  5. Access it using the Zowe Explorer VSCode plug-in. The Zowe CLI zosmf profile above will come handy here by helping you access datasets, jobs, and USS files using the popular VSCode editor.

More information

If you want to get familiar with Zowe, you can walk through the getting started guide. Some of the popular Zowe Desktop apps are covered in the user guide. Or you can register for the Zowe trial. This will take you through a guided tutorial on your individual windows client and z/OS backend server, which is pre-installed with Zowe for 3 days.

Zowe desktop

Users of Zowe can interact with the zLUX WebUi by pointing their browser at their mainframe system. This UI will include all the apps that are currently installed on the Zowe mainframe system. While it is possible to develop new apps and deploy them on your mainframe directly, it is often easier to create a local instance of the WebUi (known as zLUX) on your desktop. From there, you can play with the example-server, make changes to apps already installed, and create your own applications.

Estimated time

Completing this tutorial should take about 45 minutes.

Stand up a local version of the zLUX example server

First-time installation and use

Getting started with this requires just a few steps:

  1. Install the prerequisites
  2. Acquire the source code
  3. Set the ZSS authentication configuration
  4. Build the plug-in and add an example
  5. Build the zLUX Apps
  6. Run the server
  7. Connect in a browser

1. Install the prerequisites

Wherever the app server is installed, the following is required for running:

  • NodeJS – v6.14.4 minimum for z/OS; otherwise 6, 8, and 10 work well.

    • Download and install version of Node
    • Test node: node -v
  • npm – v6.4 minimum

    • Node download in previous step, has npm included
    • Test npm: npm -v

For building the zLUX framework and apps:

  • jdk – v8 minimum

    • Set the JAVA_HOME environment variable, if it is not already defined
    • Test java: java -version
  • ant – v1.10 minimum

    • Set the ANT_HOME environment variable, if it is not already defined
    • Add the Ant binary directory to the PATH environment variable
    • Test ant: ant -version
  • ant-contrib – v1 minimum

    • Download
    • Copy downloaded ant-contrib jar to the lib folder under apache-ant

For development:

  • git – 2.18 or higher is recommended off z/OS

    • Test git: git --version
  • ssh agent — The structure of these repositories assumes that you have SSH keys setup for Github. This assists with rapid development and automation. Git bash for Windows or PuTTY’s Pageant are just two of the tools that can help you set up and work with SSH keys over git. Generate the SSH key using the command ssh-keygen -t rsa in your git bash terminal. And add the same to GitHub.

2. Acquire the source code

To get started, first clone or download the GitHub Capstone repository, https://github.com/zowe/zlux. Make sure that you have your SSH key set up and added to GitHub.

Note: Windows users need to start ssh-agent in the background to complete the download and build the steps. Run the following commands:

// Windows Only
eval $(ssh-agent -s)  
ssh-add /c/Users/<username>/.ssh/<your_ssh_key>
git clone --recursive git@github.com:zowe/zlux.git
cd zlux
git submodule foreach "git checkout master"

At this point, you should have the latest code from each repository on your system. Continue from within the zlux-app-server folder.

3. Set the ZSS authentication configuration

By default, trivial authentication is used to allow one to login with arbitrary credentials. In app server terminology, ZSS is an agent, which is responsible for fulfilling low-level and OS-specific APIs that the app server delegates. In order to use the app server and ZSS together, your app server must be configured to use it as an agent, and set up with a security plugin which uses ZSS as an app server security provider.

Security provider setup

To add ZSS as a security provider, add the zss-auth plugin to the app server. Following Section 6 about adding plugins, you can do the following, where INSTANCE_DIR=~/.zowe and the app server in ~/my-zowe:

  1. git clone git@github.com:zowe/zss-auth.git ~/my-zowe-plugins/zss-auth
  2. cd ~/my-zowe/zlux-app-server/bin
  3. ./install-app.sh ~/my-zowe-plugins/zss-auth

Next, you need to set the configuration of the app server to prefer that security provider.wLocate and edit server.json (within INSTANCE_DIR/workspace/app-server/serverConfig/server.json, such as ~/.zowe/workspace/app-server/serverConfig/server.json). Within that file, set dataserviceAuthentication.defaultAuthentication = "zss" and dataserviceAuthentication.implementationDefaults.zss.plugins = ["org.zowe.zlux.auth.zss"].

Keep this file open to continue with the agent setup.

Agent setup (app server side)

Within the server.json file, you need to define or set agent.http.ipAddresses to a hostname or IP address where ZSS is located that is also visible to the app server. This could be ‘0.0.0.0’ or ‘127.0.0.1’ if they are located on the same system, but it may otherwise be a hostname or external IP address.

You must also define or set agent.http.port. This is the TCP port that ZSS will listen on to be contacted by the app server. Define this in the configuration file as a value between 1024 and 65535. See ZSS Configuration for more information and an example.

Note: It is highly recommended to turn on HTTPS for ZSS via configuring AT-TLS when using ZSS externally, as the session security is essential for all but trivial development environments.

As a result of the above edits to server.json, here’s an example of what it may now look like:

{
  "node": {
    "https": {
      "ipAddresses": ["0.0.0.0"],
      "port": 8544,
      "keys": ["../defaults/serverConfig/zlux.keystore.key"],
      "certificates": ["../defaults/serverConfig/zlux.keystore.cer"],
      "certificateAuthorities": ["../defaults/serverConfig/apiml-localca.cer"]
    },
    "childProcesses": [
      {
        "path": "../bin/zssServer.sh",
        "once": true
      }
    ]
  },

  "agent": {
    "host": "localhost",
    "http": {
      "ipAddresses": ["0.0.0.0"],
      "port": 8542
    },
    "attls": true
  },

  "productDir":"../defaults",
  "siteDir":"~/.zowe/workspace/app-server/site",
  "instanceDir":"~/.zowe/workspace/app-server",
  "groupsDir":"~/.zowe/workspace/app-server/groups",
  "usersDir":"~/.zowe/workspace/app-server/users",
  "pluginsDir":"~/.zowe/workspace/app-server/plugins",

  "dataserviceAuthentication": {
    "defaultAuthentication": "zss",
    "rbac": false,
    "implementationDefaults": {
      "zss": {
       "plugins": ["org.zowe.zlux.auth.zss"]
      },

      "fallback": {
        "plugins": ["org.zowe.zlux.auth.trivial"]
      }
    }
  },
}

4. Build the plug-in and add an example

Following the references above, this is how you can add a TN3270 terminal emulator app to your app server for an app server installed in ~/my-zowe:

  1. git clone https://github.com/zowe/tn3270-ng2.git ~/my-zowe/tn3270-ng2
  2. cd ~/my-zowe/tn3270-ng2
  3. Set the environment variable MVD_DESKTOP_DIR to the path of zlux-app-manager/virtual-desktop, such as export MVD_DESKTOP_DIR=~/my-zowe/zlux-app-manager/virtual-desktop
  4. cd webClient
  5. npm install
  6. npm run build (This may take some time to complete.)
  7. cd ~/my-zowe/zlux-app-server/bin
  8. ./install-app.sh ~/my-zowe/tn3270-ng2

Note: If you’re working on Windows, try %USERPROFILE%/ instead of ~/, and install-app.bat instead of ./install-app.sh.

Note: It has been reported that building can hang on Windows if you have put the code in a directory that has a symbolic link. Build time can depend on hardware speed, but should take minutes not hours.

Adding more plugins

Several plugins are available for use in Zowe. Some of them may require ZSS, which can be set up in the next steps. Here are a few plugins that you can clone to experiment with development:

  • sample-angular-app — A simple app that shows how a zLUX App front-end (here, Angular) component can communicate with an app back-end (REST) component.
  • sample-react-app — Similar to the Angular app, but using React instead to show how you have the flexibility to use a framework of your choice.
  • sample-iframe-app — Similar in functionality to the Angular and React apps, but presented via inclusion of an iframe, to show that even pre-existing pages can be included.

You can clone them all using:

git clone git@github.com:zowe/sample-angular-app.git
git clone git@github.com:zowe/sample-react-app.git
git clone git@github.com:zowe/sample-iframe-app.git

5. Build the zLUX apps

Now you’ll have the latest code for the server. The app server framework and the core plugins contain server and/or web components. Since these web components use webpack for packaging optimization, and server components may use TypeScript or other software that requires compiling, it is necessary to build the code before using the server and plugins.

You will be using utilities within the zlux-build folder for initializing and building core plugins and the framework itself. However, those tools are not needed when building individual plugins, as it is faster to build them each as needed when following this documentation..

On the host running the app server, run the script that will automatically build all included apps:

cd zlux-build

//Windows
build.bat

//Otherwise
./build.sh

This will take some time to complete.

Note: When building, NPM is used. The version of NPM needed for the build to succeed should be at least 6.4. You can update NPM by executing npm install -g npm.

Note: It has been reported that building can hang on Windows if you have put the code in a directory that has a symbolic link. Build time can depend on hardware speed, but should take minutes not hours. This will take about 5-8 mins on a Mac, and 12-15 mins on a Windows machine.

Upon completion, the app server is ready to be run.

Note: You will need to have ant and ant-contrib installed.

6. Run the server

At this point, all server files have been configured and all apps have been built, and the app server is ready to run.

From the system with the zLUX proxy server, start it with a few parameters to hook it to ZSS. Make sure to replace “8542” with your ZSS port and “192.86.32.67” with your z/OS mainframe server IP address where ZSS is installed.

cd ../zlux-app-server/bin

// Windows:
appServer.bat --allowInvalidTLSProxy=true -h 192.86.32.67 -P 8542 -s 5000

// Others:
appServer.sh --allowInvalidTLSProxy=true -h 192.86.32.67 -P 8542 -s 5000

Valid parameters for appServer are as follows:

  • -h — Specifies the hostname where ZSS can be found. Use as -h \<hostname\>.
  • -P — Specifies the port where ZSS can be found. Use as -P \<port\>. This overrides zssPort from the configuration file.
  • -p — Specifies the HTTP port to be used by the zLUX proxy server. Use as -p <port>. This overrides node.http.port from the configuration file.
  • -s — Specifies the HTTPS port to be used by the zLUX proxy server. Use as -s <port>. This overrides node.https.port from the configuration file.
  • –noChild — If specified, tells the server to ignore and skip spawning of child processes defined as node.childProcesses in the configuration file.

When the zLUX proxy server has started, one of the last messages you will see as bootstrapping completes is that the server is listening on the HTTP/s port. You should now be able to use the server.

7. Connect in a browser

Next, navigate to the zLUX proxy server which can be found at:

https://localhost:5000/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html

or

https://localhost:8544/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html

Once there, you should be greeted with a login screen and a few example apps in the taskbar at the bottom of the screen. If you set up ZSS as an authentication backend, you can log into the mainframe with your credentials:

  • Username: Refer to prereq
  • Password: Refer to prereq

By default, trivial authentication is used, which allows one to login with arbitrary credentials. But if you have followed step 4 above and configured to use zss, you can authenticate using your mainframe credential to login.

Summary

This tutorial has helped you get started with Zowe Desktop. If you have followed all the steps above, you should have a local Zowe web development environment set up on your machine.

The next tutorial is a hands-on lab that teaches you the anatomy of a Zowe Desktop app and gives you hands-on experience building your first app.

Basic troubleshooting

Where INSTANCE_DIR=~/.zowe and the app server in ~/my-zowe:

Tip 1 — Read the logs at location ~/.zowe/logs.
Tip 2 — Check the Zowe application framework troubleshooting blog for detailed error codes.

  • Unable to login with provided mainframe credentials using ZSS authentication

  • Unable to connect with localhost:8544 and using your own Zowe instance installed on your own z/OS server on backend

    • If AT-TLS is not setup on the z/OS server side, login to your z/OS instance and modify the ZSS config file ~/.zowe/workspace/app-server/serverConfig/server.json. Make sure that ipAddresses are relaxed to allow all [“0.0.0.0”].

      "https": {
      "ipAddresses": ["0.0.0.0"],
      "port": 8544,
      //pfx (string), keys, certificates, certificateAuthorities, and certificateRevocationLists are all valid here.
      "keys": ...
      , "certificates": ...
      , "certificateAuthorities": ...
      }
      

    Note: It is highly recommended that you turn on HTTPS for ZSS via configuring AT-TLS when using ZSS externally, as session security is essential for all but the most trivial development environments.

  • Unable to see specific app plugin on Zowe Desktop

    • Read ~/.zowe/logs/appServer.log and search for a plugin identifier example org.zowe.zlux.sample.angular.
    • Make sure that the plugin registration file ~/.zowe/workspace/app-server/plugins/org.zowe.zlux.sample.angular.json.

References

Zowe.org

Zowe documentation

Zowe trial registration