catchpoint/enterprise-base repository overview

⁠Synthetic Agent Docker Deployment Instructions

⁠Prerequisites

Ensure Docker is properly installed. Follow the official Docker installation documentation to install it on your system - https://docs.docker.com/engine/install⁠

Catchpoint's base docker image is available on https://hub.docker.com/r/catchpoint/enterprise-base⁠.

The base image supports the following test types:

• Ping Monitor (TCP, ICMP, UDP) [High Frequency]
• Traceroute (Insession, TCP, ICMP, UDP, QUIC)
• DNS Monitor (DNS Direct, DNS Experience)
• Web monitor - HTTP
• Javascript API - Note this is currently only supported on the AMD64 image
• FTP Monitor (FTP, FTPS, SFTP)
• SMTP
• Custom
• NTP
• IMAP
• SSL
• SSH
• Transport
• N2N

The tags are used as follows:

• preview - preview release, may have minor issues. This is promoted to stable after 2 weeks.
• stable - latest stable release.
• 2.16.x.xxx - specific versions.

Note: Catchpoint recommends using overlay2 storage format. If you are using anything other than overlay2, follow these steps after creating your Docker container.

Note: If AppArmor is enabled (Ubuntu only) then the image should be run with --security-opt seccomp=unconfined

⁠Step 1: Pull Catchpoint's docker image from Docker Hub

Pull the latest docker image from Docker Hub:

$ docker pull catchpoint/enterprise-base:preview

⁠Step 2: Create and run a container 

To run your container with the minimum recommended options, use the following command:

$ docker run -h {instanceName} --env CP_INSTANCEID={instanceID} catchpoint/enterprise-base:preview

Minimum recommended options:

• -h {instanceName} Specifies the hostname of the container. This must match the instance name in the portal.
• --cap-add SYS_ADMIN Enables mounting file systems within the container. This allows the container to run the chroot necessary for Chrome tests.
• --env CP_INSTANCEID={instanceID} Specifies the ID for this instance (must be twelve uppercase alpha-numeric characters). This is required to establish the backend relationship in the CP Portal, which is based on both the hostname and instanceID. If not provided, your instance would be assigned a different ID every time it runs, which would need to be reconfigured in the portal.

Additional options:

• --name {containerName} The name of the container in docker. Using a friendly name makes manipulating the container a little easier.
• --cap-add SYS_TIME Allows the container to set the host's time by running chronyd. Keeping time in sync is very important for accurately reporting test results. If your host is already synchronized with an NTP server, this can be omitted.
• --net=host Removes any Docker networking layers from the container and causes it to share your host's network connection, removing an additional hop from some test results. When enabled, the container will share the host’s port assignments, so only one agent container at a time may be run with this option as running multiple would cause port conflicts.
• --dns {dnsServer} Manually sets the DNS server of the container. This can be helpful to set explicitly as there may be issues with DNS tests run through the docker-internal DNS server (On Docker Desktop for Windows especially).
• -it Runs the container interactively, providing a terminal session on the running container.
• --sysctl net.ipv4.tcp_syn_retries=3 Sets the network stack for the container to limit the TCP SYN packet retries to 3 (default set by host is usually 6). This fixes some test failures that typically show as a “50005 ‘test timeout’” to correctly show as “50011 ‘connection timeout’” failure.

Automated activation options: A container can be automatically activated as an instance in the Catchpoint portal by also providing the following parameters.

• --env CP_APIKEY={apiKey} Your Catchpoint REST v2 API key.
• --env CP_NODENAME={nodeName} The name of the node to associate this instance with, as listed on the portal.

Note: It is especially important to specify a CP_INSTANCEID when using the automatic activation feature as the instance's ID will not be updated if you re-run the container with a different instanceID.

Rarely needed options:

• --cap-add NET_RAW Enables creation of raw sockets. This is needed for some test types and for packet captures. However, most docker installations have this enabled by default. It is only needed if this capability was intentionally restricted, and on some K8s providers. The /var/log/entrypoint.log file will log if this needs to be enabled.
• --cap-add NET_BIND_SERVICE Enables binding to ports below 1024. This is needed for running certain services, however most docker installations have this enabled by default. It is only needed if this capability was intentionally restricted, and on some K8s providers. The /var/log/entrypoint.log file will log if this needs to be enabled.

⁠Step 3: Log into the Interactive session for the Container

To create an interactive terminal for your container:

$ docker exec -it <<container_name>> /bin/bash 

⁠Step 4: Activate your Docker container

If you did not use the automated activation options, you can activate your docker container manually. First you need to run the command catchpoint info to get the Hostname and Machine ID. Follow the instructions in the Activating an Instance on Portal⁠⁠ section to complete container activation. You can also activate your instance using the Catchpoint utility, following the instructions here⁠⁠. Feel free to reach out to us at [email protected]⁠⁠ if you are facing any difficulties creating a docker node.