-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README for App server naming & repository renamnig, and sample App additions.
- Loading branch information
1 parent
b29c918
commit 2f1408b
Showing
1 changed file
with
36 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,16 +5,16 @@ this distribution, and is available at https://www.eclipse.org/legal/epl-v20.htm | |
| SPDX-License-Identifier: EPL-2.0 | ||
|
|
||
| Copyright Contributors to the Zowe Project. | ||
| # zlux-example-server | ||
| This is an example of a server built upon the zLUX framework. Within, you will find a collection of build, deploy, and run scripts as well as configuration files that will help you to configure a simple zLUX server with a few Apps included. | ||
| # zlux-app-server | ||
| This is the default setup of the Zowe App Server, built upon the zLUX framework. Within, you will find a collection of build, deploy, and run scripts as well as configuration files that will help you to configure a simple zLUX server with a few Apps included. | ||
|
|
||
| ## Server layout | ||
| At the core of the zLUX App infrastructure backend is an extensible server, written for nodeJS and utilizing expressJS for routing. It handles the backend components of Apps, and also can server as a proxy for requests from Apps to additional servers as needed. One such proxy destination is the ZSS - the zLUX backend component for **Z Secure Services**. It is recommended that everyone who is going to set up a zLUX install contact Rocket, which can provide the ZSS binary to use in the install. | ||
| At the core of the zLUX App infrastructure backend is an extensible server, written for nodeJS and utilizing expressJS for routing. It handles the backend components of Apps, and also can server as a proxy for requests from Apps to additional servers as needed. One such proxy destination is the ZSS - the zLUX backend component for **Z Secure Services**, a so called agent for the App server. It is recommended that everyone who is going to set up a zLUX install contact Rocket, which can provide the ZSS binary to use in the install. | ||
|
|
||
| ### ZSS & zLUX Server overlap | ||
| The zLUX Proxy Server and ZSS utilize the same deployment & App/Plugin structure, and share some configuration parameters as well. It is possible to run ZSS and zLUX Proxy Server from the same system, in which case you would be running under z/OS USS. This configuration requires that IBM's version of nodeJS is installed prior. | ||
| The zLUX App Server and ZSS utilize the same deployment & App/Plugin structure, and share some configuration parameters as well. It is possible to run ZSS and zLUX App Server from the same system, in which case you would be running under z/OS USS. This configuration requires that IBM's version of nodeJS is installed prior. | ||
|
|
||
| Another way to set up zLUX is to have the zLUX Proxy Server running under LUW, while keeping ZSS under USS. This is the configuration scenario presented below. In this scenario, you'll need to clone these github repositories to two different systems, and they'll need to have compatible configurations. For first-timers, it is fine to have identical configuration files and /plugins folders in order to get going. | ||
| Another way to set up zLUX is to have the zLUX App Server running under LUW, while keeping ZSS under USS. This is the configuration scenario presented below. In this scenario, you'll need to clone these github repositories to two different systems, and they'll need to have compatible configurations. For first-timers, it is fine to have identical configuration files and /plugins folders in order to get going. | ||
|
|
||
| ## First-time Installation & Use | ||
| Getting started with this server requires just a few steps: | ||
|
|
@@ -28,15 +28,15 @@ Getting started with this server requires just a few steps: | |
| 6. [Run the server](#6-run-the-server) | ||
| 7. [Connect in a browser!](#7-connect-in-a-browser) | ||
|
|
||
| So, with that in mind, follow each step and you'll be on your way to your first zLUX Proxy Server instance! | ||
| So, with that in mind, follow each step and you'll be on your way to your first zLUX App Server instance! | ||
|
|
||
| ### 0. (Optional) Install git for z/OS | ||
| Because all of our code is on github, yet ZSS must run on z/OS and the zLUX Proxy Server may optionally run on z/OS as well, having git on z/OS is the most convenient way to work with the source code. The alternative would be to utilize FTP or another method to transfer contents to z/OS. | ||
| Because all of our code is on github, yet ZSS must run on z/OS and the zLUX App Server may optionally run on z/OS as well, having git on z/OS is the most convenient way to work with the source code. The alternative would be to utilize FTP or another method to transfer contents to z/OS. | ||
| If you'd like to go this route, you can find git for z/OS free of charge here: http://www.rocketsoftware.com/product-categories/mainframe/git-for-zos | ||
|
|
||
| ### 1. Acquire the source code | ||
| To get started, first clone or download the github capstone repository, https://github.com/zowe/zlux | ||
| As we'll be configuring ZSS on z/OS's USS, and the zLUX Proxy Server on a LUW host, you'll need to put the contents on both systems. | ||
| As we'll be configuring ZSS on z/OS's USS, and the zLUX App Server on a LUW host, you'll need to put the contents on both systems. | ||
| If using git, the following commands should be used: | ||
| ``` | ||
| git clone --recursive [email protected]:zowe/zlux.git | ||
|
|
@@ -46,10 +46,10 @@ cd zlux-build | |
| ``` | ||
|
|
||
| At this point, you'll have the latest code from each repository on your system. | ||
| Continue from within zlux-example-server. | ||
| Continue from within zlux-app-server. | ||
|
|
||
| ### 2. Acquire external components | ||
| Apps and external servers can require contents not found in the Zowe github repositories. In the case of the zlux-example-server, there is a component which cannot be found in the repositories: a ZSS binary. | ||
| Apps and external servers can require contents not found in the Zowe github repositories. In the case of the zlux-app-server, there is a component which cannot be found in the repositories: a ZSS binary. | ||
| If you contact the Zowe project, this will be provided. | ||
|
|
||
| Afterwards, you should receive *zssServer*. | ||
|
|
@@ -64,7 +64,7 @@ mv zssServer externals/Rocket | |
| ``` | ||
|
|
||
| ### 3. Set the server configuration | ||
| Read the [Configuration](https://github.com/zowe/zlux/wiki/Configuration-for-zLUX-Proxy-Server-&-ZSS) wiki page for a detailed explanation of the primary items that you'll want to configure for your first server. | ||
| Read the [Configuration](https://github.com/zowe/zlux/wiki/Configuration-for-zLUX-App-Server-&-ZSS) wiki page for a detailed explanation of the primary items that you'll want to configure for your first server. | ||
|
|
||
| In short, ensure that within **config/zluxserver.json**, **node.http.port** OR **node.https.port + other HTTPS parameters** are set to your liking on the LUW host, and that **zssPort** is set on the z/OS host. | ||
|
|
||
|
|
@@ -77,9 +77,9 @@ Edit *../vt-ng2/_defaultVT.json* to set *host* and *port* to a valid ssh host an | |
|
|
||
| zLUX Apps can contain server and/or web components. The web components must be built, as webpack is involved in optimized packaging, and server components are also likely to need building if they require external dependencies from NPM, use native code, or are written in typescript. | ||
|
|
||
| This example server only needs transpilation and packaging of web components, and therefore we do not need any special build steps for the host running ZSS. | ||
| This server only needs transpilation and packaging of web components, and therefore we do not need any special build steps for the host running ZSS. | ||
|
|
||
| Instead, on the host running the zLUX Proxy Server, run the script that will automatically build all included Apps. | ||
| Instead, on the host running the zLUX App Server, run the script that will automatically build all included Apps. | ||
| Simply, | ||
| ``` | ||
| //Windows | ||
|
|
@@ -91,31 +91,31 @@ build.sh | |
| This will take some time to complete. | ||
|
|
||
| ### 5. Deploy server configuration files | ||
| If you are running the zLUX Proxy Server seperate from ZSS, you must ensure the ZSS installation has its configuration deployed. You can accomplish this via: | ||
| If you are running the zLUX App Server seperate from ZSS, you must ensure the ZSS installation has its configuration deployed. You can accomplish this via: | ||
|
|
||
| ``` | ||
| ant deploy | ||
| ``` | ||
|
|
||
| On the other hand, if you are running ZSS and the zLUX Proxy Server on the same host, *build.sh* and *build.bat* execute *deploy* and therefore this task was accomplished in step #4. | ||
| On the other hand, if you are running ZSS and the zLUX App Server on the same host, *build.sh* and *build.bat* execute *deploy* and therefore this task was accomplished in step #4. | ||
|
|
||
| However, if you need to change the server configuration files or want to add more Apps to be included at startup, you'll need to update the deploy content to reflect this. Simply running deploy.bat or deploy.sh will accomplish this, but files such as zluxserver.json are only read at startup, so a reload of the zLUX Proxy Server & ZSS would be required. | ||
| However, if you need to change the server configuration files or want to add more Apps to be included at startup, you'll need to update the deploy content to reflect this. Simply running deploy.bat or deploy.sh will accomplish this, but files such as zluxserver.json are only read at startup, so a reload of the zLUX App Server & ZSS would be required. | ||
|
|
||
| ### 6. Run the server | ||
| At this point, all server files have been configured and Apps built, so ZSS and the App server are ready to run. | ||
| First, from the z/OS system, start ZSS. | ||
| ``` | ||
| cd ../zlux-example-server/bin | ||
| cd ../zlux-app-server/bin | ||
| ./zssServer.sh | ||
| ``` | ||
| This should start the zssServer. If the server did not start, two common sources of error are: | ||
|
|
||
| 1. The *zssPort* chosen is already occupied. To fix, edit *config/zluxserver.json* to choose a new one, and re-run *build/deploy.sh* to have that change take effect. | ||
| 2. The zssServer binary does not have the APF bit set. Since this server is meant for secure services, it is required. To fix, execute `extattr +a zssServer`. Note you may need to alter the execute permissions of zssServer.sh in the event that the previous command is not satisfactory (eg chmod +x zssServer.sh) | ||
|
|
||
| Second, from the system with the zLUX Proxy Server, start it with a few parameters to hook it to ZSS. | ||
| Second, from the system with the zLUX App Server, start it with a few parameters to hook it to ZSS. | ||
| ``` | ||
| cd ../zlux-example-server/bin | ||
| cd ../zlux-app-server/bin | ||
| // Windows: | ||
| nodeServer.bat <parameters> | ||
|
|
@@ -126,41 +126,43 @@ nodeServer.sh <parameters> | |
| Valid parameters for nodeServer 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. | ||
| - *-p*: Specifies the HTTP port to be used by the zLUX App 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 App 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. | ||
|
|
||
| In the example where we're running ZSS on a host named mainframe.zowe.com, running on zssPort = 19997, the Proxy server running on Windows could be started with the following: | ||
| In the example where we're running ZSS on a host named mainframe.zowe.com, running on zssPort = 19997, the App server running on Windows could be started with the following: | ||
|
|
||
| `nodeServer.bat -h mainframe.zowe.com -P 19997 -p 19998` | ||
|
|
||
| After which we'd be able to connect to the Proxy server at port 19998. | ||
| After which we'd be able to connect to the App server at port 19998. | ||
|
|
||
| **NOTE: the parameter parsing is provided by [argumentParser.js](https://github.com/zowe/zlux-proxy-server/blob/master/js/argumentParser.js), which allows for a few variations of input, depending on preference. For example, the following are all valid ways to specify the ZSS host** | ||
| **NOTE: the parameter parsing is provided by [argumentParser.js](https://github.com/zowe/zlux-server-framework/blob/master/js/argumentParser.js), which allows for a few variations of input, depending on preference. For example, the following are all valid ways to specify the ZSS host** | ||
|
|
||
| - **-h myhost.com** | ||
| - **-h=myhost.com** | ||
| - **--hostServer myhost.com** | ||
| - **--hostServer=myhost.com** | ||
|
|
||
| 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. At this time, you should be able to use the server. | ||
| When the zLUX App 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. At this time, you should be able to use the server. | ||
|
|
||
| ### 7. Connect in a browser | ||
| Now that ZSS & the zLUX Proxy Server are both started, you can access this instance by pointing your web browser to the zLUX Proxy Server. | ||
| In this example, the address you will want to go to first is the location of the window management App - Mainframe Virtual Desktop (MVD). | ||
| Now that ZSS & the zLUX App Server are both started, you can access this instance by pointing your web browser to the zLUX App Server. | ||
| In this example, the address you will want to go to first is the location of the window management App - Zowe Desktop. | ||
| The URL for this is: | ||
|
|
||
| http(s)://\<zLUX Proxy Server\>:\<node.http(s).port\>/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html | ||
| http(s)://\<zLUX App Server\>:\<node.http(s).port\>/ZLUX/plugins/org.zowe.zlux.bootstrap/web/index.html | ||
|
|
||
| Once here, you should be greeted with a Login screen and a few example Apps in the taskbar at the bottom of the screen. You can login with your mainframe credentials, and try out a few Apps to see how they interact with the framework: | ||
| - tn3270-ng2: This App communicates with the zLUX Proxy Server to enable a TN3270 connection in the browser | ||
| Once here, you should be greeted with a Login screen and a few Apps in the taskbar at the bottom of the screen. You can login with your mainframe credentials, and try out a few Apps to see how they interact with the framework: | ||
| - tn3270-ng2: This App communicates with the zLUX App Server to enable a TN3270 connection in the browser | ||
| - subsystems: This App shows various z/OS subsystems installed on the host the ZSS runs on. This is accomplished via discovery of these services by the App's portion running in the ZSS context. | ||
| - sample-app: A simple app showing how a zLUX App frontend (Angular) component can communicate with an App backend (REST) component. | ||
| - sample-angular-app: A simple app showing how a zLUX App frontend (here, Angular) component can communicate with an App backend (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 & React Apps, but presented via inclusion of an iframe, to show that even pre-existing pages can be included | ||
|
|
||
|
|
||
| #### Deploy example | ||
| ``` | ||
| // All paths relative to zlux-example-server/js or zlux-example-server/bin | ||
| // All paths relative to zlux-app-server/js or zlux-app-server/bin | ||
| // In real installations, these values will be configured during the install. | ||
| "rootDir":"../deploy", | ||
| "productDir":"../deploy/product", | ||
|
|
@@ -177,11 +179,11 @@ In the configuration file, a directory can be specified which contains JSON file | |
|
|
||
| To include Apps, be sure to define the location of the Plugins directory in the configuration file, via the top-level attribute *pluginsDir* | ||
|
|
||
| **NOTE: In this repository, the directory for these JSON files is /plugins. Yet, in order to seperate configuration files from runtime files, the zlux-example-server repository copies the contents of this folder into /deploy/instance/ZLUX/plugins. So, the example configuration file uses the latter directory.** | ||
| **NOTE: In this repository, the directory for these JSON files is /plugins. Yet, in order to seperate configuration files from runtime files, the zlux-app-server repository copies the contents of this folder into /deploy/instance/ZLUX/plugins. So, the example configuration file uses the latter directory.** | ||
|
|
||
| #### Plugins directory example | ||
| ``` | ||
| // All paths relative to zlux-example-server/js or zlux-example-server/bin | ||
| // All paths relative to zlux-app-server/js or zlux-app-server/bin | ||
| // In real installations, these values will be configured during the install. | ||
| //... | ||
| "pluginsDir":"../deploy/instance/ZLUX/plugins", | ||
|
|
||