Running the agent

This page describes the various ways to run the agent.

tip

In the documentation the executable will be referred to as opscotch-agent but this might be named differently for you

In short

Here is the short answer for how to run the opscotch agent.

opscotch-agent <bootstrap> <bootstrap decryption key>

Agent arguments

The agent takes the following arguments (in order) when starting

Argument	Required	Description
bootstrap	yes	the bootstrap to load - it can be plain text or encrypted
bootstrap decryption key	no	the key to decrypt the bootstrap if it is encrypted

The bootstrap argument

The bootstrap is required to start the agent, and is passed as the first argument. The bootstrap can be passed as an argument in two modes:

Mode	Description	Example
file path	a path to a bootstrap file - it can be plain text or encrypted	opscotch-agent /path/to/bootstrapfile
base64 encoded	a base64 encoded string - it can be a plain text or encrypted bootstrap file that has been base64 encoded	opscotch-agent dGhpcyBpcyBhIGJvb3RzdHJhcAo=

The bootstrap decryption key

If the bootstrap has been encrypted you must provide the decryption key as a base64 encoded string.

opscotch-agent /path/to/encryptedbootstrapfile YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg==

Starting the agent from the command line

The simplest method of running the agent is from the command line.

As mentioned previously the agent takes at least one argument: the bootstrap, and the bootstrap decryption key if the bootstrap is encrypted.

Below is a set of examples with each argument style:

Plain text bootstrap file:

Linux/macOS

opscotch-agent /path/to/text-bootstrap.json

Windows

opscotch-agent.exe C:\path\to\text-bootstrap.json

Plain text, base64 encoded bootstrap:

Linux/macOS

opscotch-agent dGhpcyBpcyBhIGJvb3RzdHJhcAo=

Windows

opscotch-agent.exe dGhpcyBpcyBhIGJvb3RzdHJhcAo=

Encrypted bootstrap file with decryption key:

Linux/macOS

opscotch-agent /path/to/encrypted-bootstrap YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg==

Windows

opscotch-agent.exe C:\path\to\encrypted-bootstrap YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg==

Encrypted, base64 encoded string with decryption key:

Linux/macOS

opscotch-agent ZW5jcnlwdGVkIHRoaXMgaXMgYSBib290c3RyYXAK YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg==

Windows

opscotch-agent.exe ZW5jcnlwdGVkIHRoaXMgaXMgYSBib290c3RyYXAK YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg==

Running the agent from a docker container

opscotch is perfectly suited to running from a container, and you still need to provide the arguments above.

Workflow Persistence

Note that when running in a container you should take care to manage any storage for any workflow persistence.

Here is an example DockerFile:

FROM debian:9-slim

RUN apt-get update && apt-get install -y curl

COPY linux-opscotch-agent /opt/app
COPY entrypoint.sh /opt/entrypoint.sh

ENTRYPOINT [ "sh", "/opt/entrypoint.sh" ]
CMD

And here is the entrypoint.sh file:

#/bin/bash
#XMX="10g" #test value
if [ -n "$XMX" ]; then
        XMX_FLAG="-Xmx${XMX}"
fi
/opt/app $XMX_FLAG $CONFIG $KEY

These files declare a few environment variables that we can use to pass arguments to the agent:

Environment Variable	Description
CONFIG	This can be a base64 encoded bootstrap or a path to a mounted filesystem
KEY	This is the base64 encoded bootstrap decryption key

Using the files above you can start the opscotch agent in a container with the various permutations:

Mounting a configuration file from the host:

docker run -v /host/config:/config -e CONFIG=/config/bootstrap.json localhost:5000/opscotch-agent

Using a base64 encoded string:

docker run -e CONFIG=dGhpcyBpcyBhIGJvb3RzdHJhcAo= localhost:5000/opscotch-agent

Mounting an encrypted configuration file from the host, with the decryption key:

docker run -v /host/config:/config -e CONFIG=/config/encrypted-bootstrap -e KEY=YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg== localhost:5000/opscotch-agent

Using encrypted, base64 encoded string with decryption key:

docker run -e CONFIG=ZW5jcnlwdGVkIHRoaXMgaXMgYSBib290c3RyYXAK -e KEY=YSBkZWNyeXB0aW9uIGtleSB0aGlzIGlzCg== localhost:5000/opscotch-agent