Skip to main content
Version: 2.1.x

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

ArgumentRequiredDescription
bootstrapyesthe bootstrap to load - it can be plain text or encrypted
bootstrap decryption keynothe 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:

ModeDescriptionExample
file patha path to a bootstrap file - it can be plain text or encryptedopscotch-agent /path/to/bootstrapfile
base64 encodeda base64 encoded string - it can be a plain text or encrypted bootstrap file that has been base64 encodedopscotch-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:

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

Plain text, base64 encoded bootstrap:

opscotch-agent dGhpcyBpcyBhIGJvb3RzdHJhcAo=

Encrypted bootstrap file with decryption key:

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

Encrypted, base64 encoded string with decryption key:

opscotch-agent 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 VariableDescription
CONFIGThis can be a base64 encoded bootstrap or a path to a mounted filesystem
KEYThis 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