Containerized private minion (CPM) configuration

This document describes how to configure your containerized private minion (CPM).

You can do the following to customize your CPMs:

Custom npm modules

Custom npm modules are exclusive to CPM. They allow you to provide an arbitrary set of npm modules, and make them available for scripted monitors in Synthetics.

To set up the modules:

  1. Mount a directory to CPM on the Docker host. The directory must have read/write permissions, and contain a package.json following the npm official guidelines in the root of the mounted directory. Anything contained in the dependencies field will be installed by the CPM at start, and made available when running monitors on that private minion.

    Optional: You can override the root level package.json with a Node version-specific directory. This allows a script to be updated per monitor runtime if a Node version of a runtime is no longer compatible with your dependencies. See an example of this below.

    Example custom module directory

    In this example, a custom module directory is used with the following structure:

          ├── counter
          │   ├── index.js
          │   └── package.json
          └── package.json            ⇦ the only mandatory file

    The package.json defines dependencies as both a local module (i.e. counter) and an npm hosted modules (i.e. async version ^2.6.1):

          "name": "custom-modules",
          "version": "1.0.0",                                 ⇦ optional
          "description": "example custom modules directory",  ⇦ optional
          "dependencies": {
            "async": "^2.6.1",                                ⇦ npm hosted module
            "counter": "file:./counter"                       ⇦ Local module
    Example: Node version-specific overrides

    You can declare a package.json per Node version that will override the root level package.json. This allows a monitor script to be updated per monitor runtime in the event that the Node version of a runtime is no longer compatible with your dependencies. As shown in the first example, local modules can still be defined within a version specific directory. If a package.json is not defined for a specific Node version, then the root level package.json will be used to install dependencies.

    In this example, a custom module directory is used with the following structure:

          ├── 6.11.2                  ⇦ optional Node specific directory
          │   └── package.json
          └── 10.15.0                 ⇦ optional Node specific directory
          │   └── package.json
          ├── counter
          │   ├── index.js
          │   └── package.json
          └── package.json            ⇦ the only mandatory file
  2. Once you have created the custom module directory and the package.json on the Docker host, launch CPM mounting the directory at /var/lib/newrelic/synthetics/modules:

      docker run ... -v /example-custom-modules-dir:/var/lib/newrelic/synthetics/modules:rw ...
  3. Look into the docker logs for "... Initialization of Custom Modules ..." to see if the modules were installed properly, or if there were any errors. The npm installation logs will be shown.

    Now you can add "require('async');" into the script of monitors you send to this private location.

Change package.json for custom modules

Along with npm modules, you can also use Node.js modules. To change the custom modules used by your CPM, modify package.json and reboot the CPM. It will detect the change in configuration during the reboot, and then clean up and re-install.

Local modules: While your package.json can include any local module, these modules must reside inside the tree under your custom module directory. If stored outside the tree, the initialization process will fail and you will see an error message in the docker logs after launching CPM.

Permanent data storage

CPM is a stateless application and does not preserve information from prior requests or sessions by default. However, you can preserve data between launches by enabling permanent data storage. For example, you can permanently set how the minion identifies itself (e.g. Minion_ID), and use it to associate the data visible in Synthetics and Insights events with the exact minion that produced it.

To set permanent data storage:

  1. Create a directory.
  2. Launch CPM, mounting the directory at /var/lib/newrelic/synthetics.

    For example:

      docker run ... -v /example-permanent-dir:/var/lib/newrelic/synthetics:rw ...

Environment variables

Environmental variables allow you to fine-tune the CPM configuration to meet your specific environmental and functional needs. The variables are provided at startup using the -e, --env argument.

The list below shows all the environment variables that CPM supports. MINION_PRIVATE_LOCATION_KEY is required, and all other variables are optional.

Name Description Since
MINION_PRIVATE_LOCATION_KEY REQUIRED. UUID of the Private Location, as found on the Private Location Web page. 2.0.0
DOCKER_API_VERSION Format: "vX.Y" API version to be used with the given Docker service.

Default: v1.35.

DOCKER_HOST Points the minion to a given DOCKER_HOST. If absent, the default value is /var/run/docker.sock. 2.0.0
MINION_DOCKER_RUNNER_REGISTRY_ENDPOINT The Docker Registry where the Minion Runner image is hosted. Use this to override as the default. (ex. 2.1.0
MINION_API_PROXY Format: "host:port". 2.0.0
MINION_API_PROXY_AUTH Format: "username:password" - Support HTTP Basic Auth + additional authentication protocols supported by Chrome. 2.0.0
MINION_API_PROXY_SELF_SIGNED_CERT Acceptable values: true, 1, or yes (any case). 2.0.0

The maximum amount of seconds that your monitor checks are allowed to run. This value must be an integer between 0 seconds (excluded) and 900 seconds (included) (i.e. from 1 second to 15 minutes).

Default: 65 seconds for ping monitors, 180 seconds for the other monitor types.


The AppArmor profile name, if it has been applied to Docker containers running monitor scripts (i.e. Docker Runner). The AppArmor profile name must exist and be set up on the machine to work.

MINION_JVM_MB Default: "2560" (2.5GB). 2.0.0
MINION_JVM_OPTS Passes command line options to the internal JVM. See Oracle's Java documentation for more information.

Default: -server.

MINION_LOG_LEVEL When contacting New Relic Support, they may ask you to increase this to "DEBUG" or "TRACE".

Default: INFO.

MINION_VSE_PASSPHRASE​ If set, enables verified script execution and uses this value as a passphrase. 2.0.4

For more help

Recommendations for learning more: