Articles in this section

See more

Adding Agents using Docker (Versions: 9.0+)

View on Docker Hub

QuerySurge Agents can be deployed as a Docker container, which allows for flexible Agent environments and the ability to run multiple Agents on a single machine. This article discusses how to add Agents using a Docker environment.

For general Agent installation and configuration information, please see the Adding or Upgrading Agents (Linux) or Adding or Upgrading Agents (Windows) articles.

Getting Started with Docker

If you are unfamiliar with Docker and would like some more information on how to get started, please see the official Docker documentation for Getting Started with Docker.

The QuerySurge Agent Docker image is built using the Fedora Linux Docker image. This can be run on either Docker for Linux or Docker for Windows. When running on Windows, there may be additional setup involving Hyper-V or WSL2 for emulating Linux for your Docker installation. WSL2 provides the best performance benefits, since it is a full Linux kernel built by Microsoft to work directly with your Windows instance. You can learn more in the WSL and Docker for Windows documentation.

Creating an Agent Container in Docker

The QuerySurge Docker Agent repository is hosted in the Docker Hub registry under the following organization and repository name: 

querysurge/querysurge-docker-agent

You will need to make sure that you have network access to Docker Hub in order to download the appropriate container image. If you are using QuerySurge in an offline environment, you can see the following Docker article on using Command Line Save to save and transfer the Docker image. 

Using Docker Compose

If you have Docker Compose installed, this is the preferred method of running your container. To learn more about Docker Compose, you can view the official documentation for an Overview of Docker Compose.

Example:

<your_container_name>:
  container_name: <your_container_name>
  restart: unless-stopped
  image: querysurge/querysurge-docker-agent:<querysurge_version>
  volumes:
    - /opt/QuerySurge/agent/jdbc
    - /opt/QuerySurge/agent/config
  environment:
    QS_SERVER_HOSTNAME: <app_server_hostname>
    QS_SERVER_PORT: <app_server_port>
    QS_SSL: <use_ssl>
    QS_AGENT_HEAP: <agent_heap>

Example using sample values:

querysurgeagent1:
  container_name: querysurgeagent1
  restart: unless-stopped
  image: querysurge/querysurge-docker-agent:9.0.10
  volumes:
    - /opt/QuerySurge/agent/jdbc
    - /opt/QuerySurge/agent/config
  environment:
    QS_SERVER_HOSTNAME: "192.168.0.120"
    QS_SERVER_PORT: 80
    QS_SSL: "N"
    QS_AGENT_HEAP: 8192

 

Using Docker Run

The alternative to Docker Compose is to use Docker Run. To learn more about Docker Run, you can view the official Docker Run Reference.

Example:

docker run \
--name <your_container_name> \
-v /opt/QuerySurge/agent/jdbc \
-v /opt/QuerySurge/agent/config \
-e QS_SERVER_HOSTNAME='<app_server_hostname>' \
-e QS_SERVER_PORT=<app_server_port> \
-e QS_SSL='<use_ssl>' \
-e QS_AGENT_HEAP=<agent_heap> \
-h <your_container_hostname>
querysurge/querysurge-docker-agent:<querysurge_version>

Example using sample values:

docker run \
--name querysurgeagent1 \
-v /opt/QuerySurge/agent/jdbc \
-v /opt/QuerySurge/agent/config \
-e QS_SERVER_HOSTNAME='192.168.0.120' \
-e QS_SERVER_PORT=80 \
-e QS_SSL='N' \
-e QS_AGENT_HEAP=8192 \
-h querysurgeagent1
querysurge/querysurge-docker-agent:9.0.10
your_container_name The name you would like to give your Agent container
querysurge_version The version of QuerySurge Agent that your Docker Agent will run (must match your App Server version)
app_server_hostname Hostname or IP of the QuerySurge App Server
app_server_port HTTP port of the QuerySurge App Server
use_ssl

Whether your QuerySurge instance uses SSL.

"Y" for Yes
"N" for No
agent_heap The amount of memory to allocate for your Agent
(optional) your_container_hostname A manually specified hostname for the container, which will be used as the Agent name within QuerySurge. If no hostname is specified, it will be automatically generated by Docker.  
(optional) path_to_jdbc_folder_on_host

A local persistent directory that the container will use to store the JDBC drivers for the Agent. This must be accessible by your Docker filesystem (see bind mounts). You can use this option to share JDBC drivers between multiple Agents.

 

Usage Example in Docker run command: 
-v <path_to_jdbc_folder_on_host>:/opt/QuerySurge/agent/jdbc
(optional) path_to_config_folder_on_host

A local persistent directory that the container will use to store the configuration file for the Agent. This must be accessible by your Docker filesystem (see bind mounts). You can use this option to share configuration files between multiple Agents. 

 

Usage Example in Docker run command: 
-v <path_to_config_folder_on_host>:/opt/QuerySurge/agent/config

Note: Additional Agent settings are configured using the agentconfig.xml file in the config directory

Configuring Your Docker Agent

When a container is started, it will mount the config and JDBC volumes that are specified for your container. If no files exist in these directories, they will be created. If you need to modify the Agent configuration settings, you can update your container's environment variables or modify the agentconfig.xml file directly in the mounted config folder volume. 

Note: The container's environment variables will overwrite the corresponding setting in the agentconfig.xml file when the container is started

To add or remove JDBC drivers for the Docker Agent, you can manage the driver files using the mounted JDBC folder volume. 

These mounted volumes can be used individually for each Agent container, or they may be shared among multiple Agent containers. 

Note:  Dockerized Agents should not be co-deployed on your QuerySurge App Server. They should be deployed elsewhere in your environment.

Related articles