# wlpn-cli-server

> A Liberty Collective member that runs Node.js servers

Latest version **2.7.12** (published 2018-06-29) · SEE LICENSE IN LICENSE.txt license · 0 weekly downloads

## Install

```sh
npm install wlpn-cli-server
pnpm add wlpn-cli-server
yarn add wlpn-cli-server
bun add wlpn-cli-server
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; large bundle.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.7.12 |
| Published | 2018-06-29 |
| First published | 2016-07-05 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE.txt |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 27 |
| Unpacked size | 12.7 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Sam Roberts |
| Maintainers | bajtos, chrisdudley, johnbellessa, jtary, kjdelisle, kraman, qpresley, rfeng, ritch, rmg, smartmouse, tjsmith.us.ibm.com, tonyf-ibm |
| Keywords | apic-toolkit-plugin |

## Links

- npm: https://www.npmjs.com/package/wlpn-cli-server
- npm.io page: https://npm.io/package/wlpn-cli-server

## Dependencies (27)

- [pump](https://npm.io/package/pump.md) ^1.0.1
- [async](https://npm.io/package/async.md) ^2.0.1
- [debug](https://npm.io/package/debug.md) ^2.2.8
- [byline](https://npm.io/package/byline.md) ^4.2.1
- [lodash](https://npm.io/package/lodash.md) ^4.15.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [rimraf](https://npm.io/package/rimraf.md) ^2.5.2
- [express](https://npm.io/package/express.md) ^4.13.3
- [winston](https://npm.io/package/winston.md) ^2.1.1
- [bluebird](https://npm.io/package/bluebird.md) ^3.0.5
- [chokidar](https://npm.io/package/chokidar.md) ^1.6.0
- [get-port](https://npm.io/package/get-port.md) ^2.1.0
- [userhome](https://npm.io/package/userhome.md) ^1.0.0
- [body-parser](https://npm.io/package/body-parser.md) ^1.14.1
- [strong-pack](https://npm.io/package/strong-pack.md) ^1.0.0
- [posix-getopt](https://npm.io/package/posix-getopt.md) ^1.2.0
- [wlpn-password](https://npm.io/package/wlpn-password.md) ^1.0.0
- [json-file-plus](https://npm.io/package/json-file-plus.md) ^3.3.0
- [loopback-swagger](https://npm.io/package/loopback-swagger.md) ^5.5.0
- [strong-globalize](https://npm.io/package/strong-globalize.md) ^2.6.10
- [properties-reader](https://npm.io/package/properties-reader.md) 0.0.15
- [strong-supervisor](https://npm.io/package/strong-supervisor.md) ^6.2.0
- [strong-debug-utils](https://npm.io/package/strong-debug-utils.md) ^1.x
- [strong-control-channel](https://npm.io/package/strong-control-channel.md) ^2.1.1
- [apiconnect-collective-jmx](https://npm.io/package/apiconnect-collective-jmx.md) ^1.2.1
- [apiconnect-collective-unpack-cli](https://npm.io/package/apiconnect-collective-unpack-cli.md) ^1.0.0
- [apiconnect-collective-controller-api](https://npm.io/package/apiconnect-collective-controller-api.md) ^3.1.1

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 2.7.12 (latest) — 2018-06-29
- 2.1.1 (apic-v5.0.3.0) — 2016-08-08
- 2.7.11 — 2018-01-11
- 2.7.10 — 2017-08-14
- 2.7.9 — 2017-08-03
- 2.7.8 — 2017-05-19
- 2.7.7 — 2017-05-01
- 2.7.6 — 2017-02-28
- 2.7.5 — 2017-02-28
- 2.7.4 — 2017-02-26
- 2.7.3 — 2017-02-21
- 2.7.2 — 2017-01-17
- 2.6.7 — 2016-11-04
- 2.6.5 — 2016-10-25
- 2.4.7 — 2016-10-24
- … 13 more at https://npm.io/package/wlpn-cli-server/versions

## README

# 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](https://github.com/strongloop/wlpn) cli.

```
npm install -g wlpn
```

<!-- TOC -->

- [Commands](#commands)
  - [Help](#help)
  - [Run](#run)
    - [Options](#options)
    - [App/Admin Port](#appadmin-port)
  - [Start](#start)
    - [Options](#options-1)
  - [Stop](#stop)
  - [Status](#status)
  - [List](#list)
  - [Pack](#pack)
  - [Unpack](#unpack)
  - [Considerations for Application Packaging](#considerations-for-application-packaging)
    - [Install Dependencies Beforehand](#install-dependencies-beforehand)
    - [Compile on Same OS and Architecture](#compile-on-same-os-and-architecture)
- [Environment Variables](#environment-variables)
  - [WLPN_USER_DIR](#wlpn_user_dir)
  - [DEBUG](#debug)
- [Member Configuration](#member-configuration)
  - [Options](#options-2)
- [Plugin Configuration](#plugin-configuration)
  - [Options](#options-3)

<!-- /TOC -->

## 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](#wlpn_user_dir).
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](https://en.wikipedia.org/wiki/Ephemeral_port), 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.

```json
{
  "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
`foo@1.0.1`. If at a later date, you deploy this application, you might end
up with `foo@1.0.2`, 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](https://www.npmjs.com/package/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 ](https://github.ibm.com/apimesh/wlpn-cli-controller)
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](https://www.ibm.com/support/knowledgecenter/en/SSD28V_8.5.5/com.ibm.websphere.wlp.core.doc/autodita/rwlp_metatype_core.html#mtFile117). See [Plugin Configuration](#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. |

---
_Source: https://npm.io/package/wlpn-cli-server · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._