Install Experience As Is

This wiki for install is migrated to google docs at:
https://docs.google.com/document/d/1tkhj3Q4yXi0wYYzzRNU2H9l0D_9LWS7YjyYh1mHu0VE/edit?usp=sharing

1. Topics

• How to install a Zowe
• How to configure a Zowe
• How to upgrade a Zowe
• How to extend Zowe

Install

A single pax file zowe-v.r.m.pax is copied to a USS directory. The user unpaxes this and runs two scripts. zowe-install.sh which creates and configures a single runtime directory with 25 sub directories. By default this is ~/zowe/v.r.m so it is created in the user's home directory. A proclib ZOWESVR is created.
A second script zowe-apf-server-install.sh creates and configures the ZWESIS01 proclib that is the APF authorized load module, together with its associated z/OS Load library and parm library. The script also configures security and other settings in support of ZWESIS01.

Pain points

Lack of an enterprise installer that allows rollback, audit of install history, customer production acceptance Because the installer performs configuration depending on the permission of the user performing the install success is variable

Configure

Configuration of Zowe is done before the install occurs. The file zowe-install.sh can be edited to change defaults for port values and other settings and values. During the install these values overwrite values held in a number of files in the configuration. These are .sh, .html, .json.

Pain points

Because configuration is done pre-install, changes to port values, certificate settings, and other values cannot be easily amended post install.

  ~/zowe/1.0.0/
    api-mediation
    api-catalog
    ...
    zlux-app-manager
    zlux-app-server
    ...

This represents the components for the core Zowe components (API Mediation Layer, Desktop)

This contains binaries for the node, Java and c executables for the API Mediation Layer (APIML) and the Virtual Desktop scripts to start and stop Zowe and its servers, that also includes the MVS, USS and JES Explorer information about the launch parms such as ports, location of Java, node, TCP/IP addresses extension folders where extenders drop in new entries for the APIML and new Virtual Desktop apps.
log folders preference persistence data

Upgrade

Logging

As is: Currently logs are disparate.
Ideas: Look at consolidating logs.

Installation Directory Structure - To Be

$hog Recommended approach by the project needed. Related to logging but a bit bigger picture. My preference is that we divide install into several areas:

Binaries

Binaries are the artifacts from building Zowe from Source. These are the Zowe artifacts and do not carry installation (site) specific information.

Recommendation: /usr/lpp/zowe/Current -> n.n.n /usr/lpp/zowe/n.n.n

Configuration

This needs to be outside of the installation directory for binaries. Persists across upgrades and each component would need to respect the existence of a pre-existing configuration. Options are:

/etc/zowe/ /var/zowe/etc

$hog preference is the latter as it is consistent with the approach by z/OSMF so its familiar to existing customers and supports a consolidated PoV. Havent thought through security considerations.

At install time settings in the .yaml file for ports and other details are sed injected into a number of configuration files used by various runtimes (zLUX, ZSS, APIML, explorers, ...). Problem: if a user wants to update these post install they need knowledge of which file(s) to update, likewise if they want to query the values. Solution: Have a central configuration .json file that is dynamic/live/current, and the runtimes pick up their values from there.

Plex

Desire to install Zowe into a central plex wide location, e.g. /usr/lpp/zowe and have different configurations per LPAR. This allows for easy upgrade of a central location of binaries across LPAR.

Logs

A place where Zowe logs are placed outside of the install dir. Prefer /var/zowe/logs/... where /... can be logs by application or some other structure. Prefer to follow the log paradigm used by Linux for familiarity.

User Specific Preferences

A .zowe profile is created in the ${HOME} directory for each user. Would require an OMVS segment for every user ... not sure if that is feasible or not. This would contain configuration information for the user, labnguage preferences, colors, skins, initial apps, Login Items, ...

Docs

As is: Doc is incomplete.

User research comment: “Better/Complete installation and Configuration documentation is the best thing that can be done to help folks get up and running so they can see the benefits of Zowe."

Ideas:

• Observe real user install process to identify gaps: What's missing, what needs more clarification
• Reorganize the whole user guide, especially the installation and configuration section and solicit user feedback.
• More troubleshooting information

---

As is: Pre-reqs are hard to install. Users follow the doc but was stuck at Node. Some steps for installing Node are not necessary for installing Zowe. We currently point users to Node.js doc for how to install Node and tell users in our doc that some steps are not needed. This is not ideal user experience. When users perform the installation, they likely will forget what's needed VS what's not.

Ideas:

• For Node install, similar to what we're doing for z/OSMF Lite, document the high level procedures required for Zowe in Zowe doc.
• For system requirements or prerequsiste configuration, we need a more clear list or better organization of information. A consolidated checklist for example.

Ports

Currently we have a lot of serverPort=xxxx in the zowe-install.yaml file. Ideas;

• Have a portRange specified and the installer picks off ports sequentially to assign them when needed (which is what users updating the .yaml tend to do anyways.
• The port for the API mediation layer is the only one that should be exposed so needs to possibly be configured explicitly so leave this

Deployment

Our current modular monolith deployment topology has repercussions for installation, upgrade, scale, clustering, and end-user security audit requirements. Install is generally easier as a modular monolith, as well as passing a security audit (single new STC as opposed to one-per-server). However upgrade, scale, and clustering requires total service shutdown and cloning. We should consider alternate install/deployment with component subset analysis for High Availability/Sysplex-Aware installations.

One off-the-cuff possibility:

• ZOWEAPIL (3 APIML Services in one STC)
• ZOWEDKTP (Zowe Desktop STC)
• ZOWEXPLR (All Zowe Explorer-Server servers)

This allows us to scale out each STC separately.

• Zowe Desktop likely requires one installation per SYSPLEX (unless HA cluster- but some system automation should allow recovery of address spaces).
• ZOWEAPIL can be run across LPARs for HA/load balancing (consider moving catalog UI to DKTP STC?).
• ZOWEXPLR can be run across LPARs for HA/load balance/system-specific reporting (like APIML, consider plugins in ZOWEDKTP and just REST servers in ZOWEXPLR).

Open Questions:

• ZSS Server Requirements (One-per-LPAR?)
• Alternative deployments
• User sentiment towards number of address spaces Zowe requires

More from @MattHogstrom on scale/cluster/ into Sysplex environments:

So far we’ve been focusing on Zowe running in an LPAR or with a specific consumer … I’m thinking forward to how do we want to have people deploy Zowe in a Sysplex (or even across Sysplexes if that makes sense) … I included a two slide deck (very rough) on what I think is an LPAR deployment and then a Sysplex deployment. The main difference is that I think ZSS will likely need to run one instance on every LPAR (to support CB running) and then the other Zowe isntances can call out to the other Sysplex ZSS instances as needed for routing … not sure about the APIML but would we want to run multiple instances (to support availbility on two or more LPARs in a plex) and how do we want to route requests (Sysplex Distributor?) … I figured I’d kick off this discussion in Core since it applies to all projects … thoughts ?