Manage GroundRunners for Connections

To enable the commands within a chain to interact with an on-premise remote data source, IT admins or someone familiar with your organization's network and firewall settings install and set up a GroundRunner on a dedicated server, such as where you host the connected data source. When you add a command to a chain, you assign its connection to a GroundRunner to perform the task within the data source.

System Requirements

GroundRunners require Java® version 8 or higher.

GroundRunners support these operating systems, with no external library dependencies:

• Microsoft Windows® Desktop 7 and 10, 32- and 64-bit
• Microsoft Windows® Server 2008, 2012, 2012 R2, 2016, and 2019
• Linux® Redhat and Ubuntu
• Solaris® 11, 11.1, 11.2, 11.3, and 11.4
• macOS® Sierra, High Sierra, and Ubuntu

While GroundRunners require limited server resources, we recommend at least:

• 512MB of available random access memory (RAM)
• 100GB of available disk space

The recommended host configuration includes a virtual machine configured with:

• Two to four processors
• 8GB of system memory
• A solid state drive (SSD) storage device

Install a GroundRunner for Windows via CLI

1

From Chains , click Admin  settings , and select Runners  computer, Downloads.

2

Select the GroundRunner for your operating system, and click Download.

3

Download the installation file to its own directory within your program files, such as c:\Program Files (x86)\wdata, and unzip the file.

4

Extract its files to the root of the directory:

• GroundRunner.exe
• GroundRunnerMonitor.exe
• installer.exe

5

From the Windows Command Line interface (cmd.exe) (CLI), as an administrator, run the command c:\Program Files (x86)\wdata\installer.exe install, and accept all defaults.

• For the path, create a Files folder within the new directory, such as C:\Program Files (x86)\Wdata\Files. Select to create it if it doesn't exist.
• For the authorization hostname (AUTH_HOST):
  • If in North America, enter h.app.wdesk.com/s/wdata/oc/app.
  • If in Europe, enter h.eu.wdesk.com/s/wdata/oc/app.
• For the company token, enter the value generated for your organization.

  To find your company ID from Chains , click Admin settings , and select Runners computer, Downloads.

6

Delete all files from the directory except the GroundRunner executable directory.

7

Select whether to run the GroundRunner as a service or a foreground process.

• To run as a service, in the CLI, enter the command sc start GroundRunner; or, in Windows Service Manager, start the HostRunner service.
• To run as a foreground process, in the CLI, enter the commands:

cd c:\Program Files (x86)\wdata
GroundRunner.exe

8

To register the runner from Chains , click Admin, and select Runners. Under Pending Registration, enter a short, descriptive name for the runner, such as <datasource>-GroundRunner, and click Activate.

Install a GroundRunner for Windows via MSI 

1

From Chains , click Admin  settings , and select Runners  computer, Downloads.

2

Select the GroundRunner for your operating system, click Download, and unzip windows_amd64_ground_runner.zip.

3

To open the GroundRunnder Setup Wizard, run GroundRunner.msi, and click Next.

4

Review and accept the terms in the license agreement, and click Next.

5

For Destination Folder, enter the path to where to install the GroundRunner, such as C:\Program Files\GroundRunner\, and click Next.

6

In Platform company token, enter your company ID.

To find your company ID from Chains , click Admin settings , and select Runners computer, Downloads.

7

In Platform auth host:

• If in North America, enter h.app.wdesk.com/s/wdata/oc/app.
• If in Europe, enter h.eu.wdesk.com/s/wdata/oc/app.

8

If using a proxy server, do one of the following:

• To reach the proxy server, in Proxy host, enter its valid URL, including the port if necessary. For example, http://yourproxy:3000.
• To bypass the proxy server, in No proxy host, enter a comma-separated list of hosts to reach directly instead.

9

Click Next, Install, and Finish. If prompted for User Account Control, click Yes to enable the installer to make changes to your device.

10

From Windows Service Manager, right-click on GroundRunner, and select Start.

Install a GroundRunner for Linux or macOS

1

From Wdata Chains, click Admin  settings, and select Runners  computer, Downloads.

2

Select the GroundRunner for your operating system, and click Download.

3

Download the installation file to its own directory, such as /home/<username>/wdata/, and unzip the file.

4

In a CLI, enter the command sudo .installer install. Accept all defaults.

• For Linux, to determine your init system, check for the directory /usr/lib/systemd for a systemd-based system, or /usr/share/upstart for an upstart-based system.
• For macOS, neither system init applies. Instead, run the GroundRunner as a foreground process.

5

Delete all files from the directory except the GroundRunner executable directory.

6

In the CLI, run the GroundRunner as a foreground process or—for Linux—a service.

• To run as a service, enter the commands cd /home/<username>/wdata/GroundRunner and sudo ./cli start
• To run as a foreground process, enter the commands:

cd /home/<username>/wdata/GroundRunner
sudo ./GroundRunner

7

To register the runner from Wdata Chains, click Admin settings, and select Runners computer. Under Pending Registration, enter a short, descriptive name for the runner, such as <datasource>-GroundRunner, and click Activate.

Check the Status of a Runner

GroundRunners require a constant heartbeat to exchange messages with instructions on how to run jobs and any related information. If a GroundRunner goes offline, it can no longer respond to commands, and administrators receive a warning email.

To view the online/offline status of a GroundRunner, from Wdata Chains, click Admin settings, Runners computer, and view which runners are Pending Registration, Active, or Inactive.

To view the resource status of the host operating system for a runner, select its Show status.

Manually Update a GroundRunner

While rare, you may need to manually upgrade a GroundRunner.

For Windows via CLI

1

From Wdata Chains, click Admin  settings, and select Runners  computer, Downloads. 

2

Select the latest GroundRunner for your operating system, and click Download.

3

In Windows Services Manager, stop the GroundRunner service.

4

Move the downloaded GroundRunner installation file to its own directory—such as c:\groundrunner_upgrade—and unzip its files.

5

Copy and paste these uncompressed files to the diretory where the GroundRunner binaries are installed:

• GroundRunner.exe
• GroundRunnerMonitor.exe

6

In Windows Services Manager, restart the GroundRunner service.

For Windows via MSI

To update the GroundRunner, download and install the latest MSI, and uninstall any previously downloaded versions.

For Linux or macOS

1

From Wdata Chains, click Admin  settings, and select Runners  computer, Downloads.

2

Select the latest GroundRunner for your operating system, and click Download.

3

On the server hosting the GroundRunner, navigate to the directory where the service runs.

4

In a CLI, enter the command sudo ./cli stop to stop the GroundRunner service.

5

Move the downloaded GroundRunner installation file to its own directory—such as /home/<username>/groundrunner_upgrade/—and unzip its files.

6

Copy and paste these uncompressed files to the diretory where the GroundRunner binaries are installed:

• GroundRunner
• GroundRunnerMonitor

7

In the CLI, enter the command sudo ./cli start to restart the GroundRunner service.

Uninstall a GroundRunner

For Windows via CLI

1

Stop the GroundRunner's service:

• If running as a service, use Windows Service Manager, or, in the CLI, enter the command sc stop GroundRunner
• If running as a foreground process, press the key sequence <ctrl> <c>

2

In the CLI, as an administrator, enter the command cli .exe uninstall

3

Delete the GroundRunner executable directory.

For Windows via MSI

To remove the GroundRunner service, in Apps & features from Windows Settings, select GroundRunner (64 bit), and click Uninstall.

For Linux or macOS

1

Stop the GroundRunner's service:

• If running as a service, in the CLI, enter the commands cd /home/<username>/wdata/GroundRunner and sudo ./GroundRunner.
• If running as a foreground process, press the key sequence <ctrl> <c>.

2

In the CLI, enter the command sudo ./cli uninstall.

3

Delete the GroundRunner executable directory.

GroundRunner Configuration Settings and Whitelist Domains

To enable communication with its data source, you may need to open firewall ports on the server where the GroundRunner is installed. With some GroundRunners, you can edit the file GroundRunner.config in the directory where the binaries are installed to change its configuration settings.

Configuration	Settings
PORT	0 to 65535. By default, GroundRunners use port 8821 to communicate with one another. However, a port is required only if GroundRunners on different servers share command outputs inside your network.
COMPANY_TOKEN	Leave as default, unless the GroundRunner is configured for a different tenant
LOG_LEVEL	info or debug
PROTOCOL	Leave as default
HTTP_PROXY_URL	If using a proxy server, its valid URL, including the port if necessary. For example, http://yourproxy:3000
LONG_POLL	If using a proxy server, set to true to instruct the runner to use long-polling to retrieve commands. To ensure performance, use long-polling only if web sockets aren't supported by your proxy server or firewall.
NO_PROXY	To bypass the proxy server, provide a comma-separated list of hosts to reach directly instead. To include multiple hosts based on a common pattern, use the * wildcard.