Miss any of our Open RFC calls?Watch the recordings here! »

@americanexpress/one-app-runner

6.10.0 • Public • Published

@americanexpress/one-app-runner

A command line interface (CLI) tool for running One App locally.

one-app-runner allows you to work locally on your Holocron Module without having to clone One App.

It works by pulling a Docker image for One App and mounting your module to it as a volume.

Note: If you are making changes to One App at the same time you are making changes to your Module(s) then you will still need to clone One App, serve your module to it, and start it yourself.

🤹‍ Usage

Note that Docker is required and must be installed before one-app-runner can be used.

Quick start

In any Holocron Module directory:

  1. Install:
npm install --save-dev @americanexpress/one-app-runner
  1. Add the one-app-runner command to your npm start script and a runner config to your module's package.json. See below for an example:
package.json
"scripts"{
  "start": "one-app-runner"
},
"one-amex"{
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "parrotMiddleware": "./dev.middleware.js"
  }
}

Use the runner config to tell one-app-runner what module map and One App version to use, what your root module is, where your module is (current directory in this case), and optionally where your Parrot mocks middleware file is located.

Command options reference

one-app-runner can be configured via command options or a configuration object in package.json:

docker-image [Required]

Docker image to use for One App. It allows you to specify what Docker image and tag to pull down for One App. This can be an image you have built and tagged locally but is not published to a Docker registry. Whatever value is provided is passed down to docker pull and docker run.

Sample usage:

npx @americanexpress/one-app-runner --docker-image oneamex/one-app-dev:5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json"
  }
}

module-map-url

Location of module map for One App to use to fetch modules. This option is required.

Sample usage:

npx @americanexpress/one-app-runner --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "rootModuleName": "frank-lloyd-root"
  }
}

root-module-name [Required]

Name of the module to use as a root module for your One App instance.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

modules [Optional]

This option is required if module-map-url is not provided.

Path to local module(s) to serve to One App. This can be either an absolute or a relative path to a Holocron Module's root directory. Supports serving multiple modules at the same time as well.

Sample usage:

npx @americanexpress/one-app-runner --modules ../frank-lloyd-root --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json
 
# or to serve multiple modules 
npx @americanexpress/one-app-runner --modules ../frank-lloyd-root ../cultured-frankie --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "modules": [
      ".",
      "../frank-lloyd-root"
    ],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

parrot-middleware [Optional]

Path to parrot dev middleware file for One App to use for Parrot mocking. This option must be used in conjunction with the --module option.

For more information on setting up parrot dev middleware, check out the One App Mocking APIs recipe.

Sample usage:

npx @americanexpress/one-app-runner --parrot-middleware ../frank-lloyd-root/dev.middleware.js --module ../frank-lloyd-root --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "parrotMiddleware": "./dev.middleware.js",
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

If middleware is defined in the package.json, you can use the --no-parrot-middleware option to temporarily disable it.

dev-endpoints [Optional]

Path to dev endpoints file for One App to use for the One App Dev Proxy set up. This option must be used in conjunction with the --module option.

For more information on setting up your dev endpoints file, check out the Configuring One App with your API URLs guide.

Sample usage:

npx @americanexpress/one-app-runner --dev-endpoints ../frank-lloyd-root/dev.endpoints.js --module ../frank-lloyd-root --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "devEndpoints": "./dev.endpoints.js",
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
  }
}

output-file [Optional]

Path to a file to which One App logs should be redirected to. Using this option will send all One App logs to given file and will result in no logs from One App being sent to your terminal.

Sample usage:

npx @americanexpress/one-app-runner --output-file ../one-app.log --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root

Or in package.json

"one-amex"{
  "runner": {
    "outputFile": "./one-app.log",
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x"
  }
}

docker-network-to-join [Optional]

Connect the One App container to a network. The value gets passed to the docker flag --network

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --docker-network-to-join my-network

Or in package.json

"one-amex"{
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "dockerNetworkToJoin": "my-network"
  }
}
 

create-docker-network [Optional]

This option requires docker-network-to-join to be used as the network name.

Creates a new docker network using the network name provided.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --create-docker-network --docker-network-to-join my-network

Or in package.json

"one-amex"{
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "dockerNetworkToJoin": "my-network",
    "createDockerNetwork": true
  }
}

use-host [Optional]

Use req.headers.host instead of localhost for one-app-dev-cdn

Note: This flag is required when using one-app-runner for browser tests on a CI environment so the one-app-dev-cdn can be accessed by other containers running on the same network.

Sample usage:

npx @americanexpress/one-app-runner --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json  --module ../frank-lloyd-root --use-host

Or in package.json

"one-amex"{
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x",
    "useHost": true
  }
}

envVars [Optional]

Environment variables to provide to One App instance.

Sample usage:

npx @americanexpress/one-app-runner --envVars '{ "ONE_CONFIG_ENV": "production" }' --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json
// or
npx @americanexpress/one-app-runner --envVars.ONE_CONFIG_ENV=production --root-module-name frank-lloyd-root --one-app-version 5.x.x --module-map-url https://example.com/cdn/module-map.json

Or in package.json

"one-amex"{
  "runner": {
    "envVars": {
      "ONE_CONFIG_ENV": "production"
    },
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "oneAppVersion": "5.x.x"
  }
}

Proxy Support

one-app-runner respects the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables and passes them down to the One App docker container.

Make use of these environment variables if the remote module map or modules you want One App to use are inaccessible without the use of a proxy server.

Test Environment

one-app-runner-test

Creates a new instance of one-app-runner that runs in the background detached from the parent process. This option is useful to run a test suite against the running One App container.

package.json
"scripts"{
  "start": "one-app-runner",
  "start:test": "one-app-runner-test"
},
"one-amex"{
  "runner": {
    "modules": ["."],
    "rootModuleName": "frank-lloyd-root",
    "moduleMapUrl": "https://example.com/cdn/module-map.json",
    "dockerImage": "oneamex/one-app-dev:5.x.x",
    "parrotMiddleware": "./dev.middleware.js"
  }
}

create-runner-env

This command generates random ports and values for the following environment variables:

HTTP_PORT
HTTP_ONE_APP_DEV_CDN_PORT
HTTP_ONE_APP_DEV_PROXY_SERVER_PORT
HTTP_METRICS_PORT
NETWORK_NAME

It stores them in a .env file to be shared across the test environments and one-app-runner

This command should be executed before starting one-app-runner-test

Install

npm i @americanexpress/one-app-runner

DownloadsWeekly Downloads

84

Version

6.10.0

License

Apache-2.0

Unpacked Size

43.4 kB

Total Files

8

Last publish

Collaborators

  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar