wlpn-cli-server

A wlpn plugin for controlling, packaging, unpackaging and managing Liberty Collective Members and their Node.js applications.

This plugin comes included with the wlpn cli.

npm install -g wlpn

• Commands
  • Help
  • Run
    • Options
    • App/Admin Port
  • Start
    • Options
  • Stop
  • Status
  • List
  • Pack
  • Unpack
  • Considerations for Application Packaging
    • Install Dependencies Beforehand
    • Compile on Same OS and Architecture
• Environment Variables
  • WLPN_USER_DIR
  • DEBUG
• Member Configuration
  • Options
• Plugin Configuration
  • Options

Commands

Help

General server plugin help:

wlpn server:help

Specific command help:

wlpn server:<cmd> [-h|--help]

Run

To run the application in the foreground, run:

wlpn server:run <serverName> [options..]

The <serverName> parameter is the name of the folder contained within the configured WLPN_USER_DIR location. As a default, this will log all output to the stdout and stderr streams of the current terminal.

Options

| Flag | Description | |------|-------------| | -W, --appPort=PORT | The port number that the Node.js application will be bound to. | | -A, --adminPort=PORT | The port number that the Manager will listen on for command-and-control. |

App/Admin Port

By default, the app and admin ports will be ephemeral ports, but you can change configuration to make either of these ports static.

To set the app port at runtime, use the --appPort flag: wlpn server:start <serverName> --appPort=<portNumber>

To set the admin port at runtime, use the --adminPort flag: wlpn server:start <serverName> --adminPort=<portNumber>

You can also set the application port via the join.json config file, in WLPN_USER_DIR/<serverName> or server.json in the WLPN_USER_DIR/<serverName>/package directory with the appPort/adminPort property.

// server.json
{
  "appPort": 9000,
  "adminPort": 9001
}

NOTE: Using the server.json file to enforce your application port binding will override every other form of binding except for command-line arguments. You should only do this if you know that each host machine will have this port free for use. Your application will not run correctly if the assigned port is not available!

Start

Start is similar to run, but it automatically backgrounds the process after some initial configuration loading and prerequisite checks.

wlpn server:start <serverName> [options..]

As a default, this will log all output to the application's log folder, which can be found at $WLPN_USER_DIR/<appName>/log.

Options

| Flag | Description | |------|-------------| | -W, --appPort=PORT | The port number that the Node.js application will be bound to. | | -A, --adminPort=PORT | The port number that the Manager will listen on for command-and-control. |

Stop

Stop will turn off the application instance, and then the instance of wlpn-cli-server responsible for managing that app instance.

wlpn server:stop <serverName>

Status

Determine whether or not the application is running with this command.

wlpn server:status <serverName> [-p|--parseable]

By default, this command will print a status message if the application is running. Server your-example-app is running with process ID 12345.

If the application is not running, an error will be returned instead. Error: Server your-example-app is not running.

If you provide the -p or --parseable flag, it will return a JSON payload that either:

• describes the application's process ID (pid), the application port (appPort) and the command-and-control port (adminPort), if applicable.
• returns an error property with the appropriate error message.

{
  "pid": 12345,
  "adminPort": 32101,
  "appPort": 32102
}

List

List all of the installed application instances in the WLPN_USER_DIR with this command.

wlpn server:list

Please note that this does not tell you if the applications are correctly installed or configured, only that they are present in the directory.

Pack

To prepare an application for use with wlpn-cli-server, you can use the plugin as a utility for packaging the application.

wlpn server:pack <srcPath>

This will generate a gzipped tarball in the current directory based on the contents of the given srcPath.

When packaging your application, make sure you install your dependencies beforehand, as the wlpn-cli-server runtime will not check to make sure your dependencies are installed!

Unpack

If you would like to manually setup a member host with an instance of an application, you can run the unpack command to unzip your .tgz archive.

wlpn server:unpack <serverName> <srcPath>

This will unpack the tarball in srcPath to the $WLPN_USER_DIR/<serverName> directory.

Considerations for Application Packaging

Install Dependencies Beforehand

Dependencies we resolve on your behalf may not be identical to the ones you pull down during your development and testing. For example, if you have a dependency on foo: foo@^1.0.0, npm might fetch you [email protected]. If at a later date, you deploy this application, you might end up with [email protected], which may or may not contain a bug that causes havoc in your application!

"If I'm worried about that, I'll use npm shrinkwrap!"

If you're not careful about how you shrinkwrap, you can accidentally cause all kinds of problems for yourself such as:

• Shrinkwrapping with optionalDependencies included makes them not-optional! This will mean that OS-specific packages will now cause failures on installation or at runtime.
• Shrinkwrapping things in the incorrect order will prioritize the versions in the deepest parts of your hierarchy (meaning if your app is a collection of your own libraries, you need to carefully shrinkwrap them from the bottom-up) to avoid unexpected versions of dependencies, and then you'll have to synchronize/dedupe those dependencies yourself.

Additionally, some users deploy to systems that have limited or controlled access to the internet; they might not be able to reach npmjs.com or some other third-party mirror to resolve their dependencies.

Many companies will require that production environments do not contain compilers, build tools, or anything that might assist an attacker in subverting security.

Compile on Same OS and Architecture

Since we require you install your own dependencies, we must also require you to be mindful of where you do this installation; if you build your package on OS X and attempt to deploy it onto a Ubuntu machine, you might run into issues if any of your modules require a node-gyp build step.

Some modules side-step the issue by pulling pre-built binaries for the OS at runtime when available, but you shouldn't assume that all of your favourite dependencies (or the favourite dependencies of those modules!) do this as well.

Environment Variables

There are some environment variables that you can set before calling wlpn-cli-server commands

WLPN_USER_DIR

The WLPN_USER_DIR defaults to $HOME/wlpn, and is where all of your application instance folders reside.

DEBUG

This plugin use of the debug library, and thus, you can retrieve debug output during the application run. All of the debug output this module generates is prefixed with the wlpn-cli-server: prefix.

Examples: All wlpn-cli-collective messages:

$ DEBUG=wlpn-cli-server:* wlpn server:run my-app [options..]

All debug messages:

$ DEBUG=* wlpn server:run my-app [options..]

NOTE: We STRONGLY advise against using this option in production; you should never log debug output in this way if your application handles sensitive data.

Member Configuration

Here are some of the configuration options you can use in the join.json/server.json of a member application. Note that many of these values are automatically populated when making use of the wlpn-cli-controller's join command.

Options

| Key | Description | |------|-------------| | hostName | The name of the host machine the application is running on. | | userDir | The path of the user directory (defaults to WLPN_USER_DIR). | | serverName | The name of the application (defaults to the value specified during collective join) | | keystorePassword | The password for the credential keystore provided during collective join, obfuscated by default. | | controllerList | The list of all collective controller servers to communicate with during operations | | pluginConfiguration | A list of configuration keys for setting up the plugin. Some of these values map directly to Liberty's pluginConfiguration. See Plugin Configuration for more details. |

Plugin Configuration

Below are a list of keys for setting up the pluginConfiguration of wlpn-cli-server. Note that not all Liberty configuration options are supported!

Options

| Key | Description | |------|-------------| | ConnectTimeout | The duration to wait before declaring connection timeout. Defaults to 5 seconds. | | WsIoTimeout | The WebSocket IO timeout. Defaults to 30 seconds. | | IoTimeout | The serverIoTimeout. Defaults to 900 seconds. | | WsIdleTimeout | The connection timeout for an idle WebSocket connection between the plugin and the application. Defaults to 900 seconds. |