Docker

This guide covers installing the Dstl 8 agent on Docker hosts.

Prerequisites

• Docker installed and running

• Organization ID (provided by Dstl8)

• Cluster/Group name (optional, defaults to docker)

• Deployment environment label (e.g., prod, dev, staging)

• Docker admission token (generated in the Dstl8 UI)

• Config and data endpoint URLs (provided in the Dstl8 UI)

---

Installation

Quick Install

The Dstl 8 UI generates a custom installation command for your Docker host. Simply provide your deployment environment and optionally a cluster/group name, and the UI will generate the complete command with all required credentials.

Generated Command Example:

curl -fsSL https://install.controltheory.com/scripts/install.sh -o install.sh && bash install.sh \
  -p docker \
  -i <org-id> \
  --docker-token <token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name <host-name> \
  -e <environment>

Installation Options

With Custom Cluster/Group Name:

bash install.sh -p docker \
  -i <org-id> \
  --docker-token <token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name production-host-01 \
  -e prod

Without Cluster Name (Uses Default):

If you don't specify a cluster name, it defaults to docker:

bash install.sh -p docker \
  -i <org-id> \
  --docker-token <token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  -e prod

Custom Docker Image Tag:

To install a specific version of the agent:

bash install.sh -p docker \
  -i <org-id> \
  --docker-token <token> \
  --config-endpoint <config-url> \
  --data-endpoint <data-host:port> \
  --cluster-name myhost \
  -e prod \
  --docker-tag v1.3.10

---

What Gets Installed

The installation script:

1. Pulls the ControlTheory supervisor Docker image (controltheory/supervisor)

2. Creates a Docker container with the necessary configuration

3. Connects the agent to your Dstl 8 organization

4. Starts monitoring and telemetry collection

5. Exposes OTLP receiver ports for accepting telemetry data

Default Docker Image: controltheory/supervisor:v1.3.10

OTLP Receiver

The Docker agent runs as an OTLP (OpenTelemetry Protocol) receiver and automatically exposes the following ports on the host:

• Port 4317 - OTLP gRPC endpoint (mapped to container port 1757)

• Port 4318 - OTLP HTTP endpoint (mapped to container port 1758)

Applications running on the same host or network can send OpenTelemetry data to these endpoints:

# OTLP gRPC endpoint
http://localhost:4317

# OTLP HTTP endpoint
http://localhost:4318

---

Verify Installation

After installation, check the status of your Docker agent:

bash install.sh -o status -p docker

This command displays:

• Container running status

• Container ID and name

• Image version

• Configuration details

• Health check information

Manual Container Check:

You can also verify the container is running:

docker ps | grep controltheory

View Container Logs:

To see the agent logs:

docker logs <container-id>

Or follow logs in real-time:

docker logs -f <container-id>

---

Uninstall

To completely remove the Dstl 8 agent from your Docker host:

bash install.sh -o uninstall -p docker

This command:

• Stops the ControlTheory supervisor container

• Removes the container

• Cleans up associated resources

Note: The Docker image is not removed. To manually remove the image:

docker rmi controltheory/supervisor:v1.3.10

---

Troubleshooting

Common Issues

Container Not Starting:

Check the container logs for errors:

docker logs <container-id>

Common causes:

• Incorrect admission token

• Network connectivity issues

• Port conflicts (ports 4317/4318 already in use)

Port Conflicts:

The Docker agent requires ports 4317 (OTLP gRPC) and 4318 (OTLP HTTP) to be available. If these ports are already in use, you'll see an error during installation.

Check which processes are using these ports:

sudo lsof -i :4317
sudo lsof -i :4318

Or on some systems:

sudo netstat -tulpn | grep 4317
sudo netstat -tulpn | grep 4318

You'll need to stop the conflicting service or modify the Docker container's port mappings.

Network Connectivity:

Verify the Docker host can reach the config and data endpoints:

curl -v <config-endpoint>
curl -v <data-endpoint>

Permission Denied:

Ensure your user has permission to run Docker commands. You may need to:

sudo usermod -aG docker $USER

Then log out and back in for changes to take effect.

Container Crashes or Restarts:

Check container restart count:

docker inspect <container-id> | grep RestartCount

Review container logs to identify the cause of crashes.

Getting Help

For installation issues:

1. Run the status check: bash install.sh -o status -p docker

2. Collect container logs: docker logs <container-id>

3. Verify network connectivity to endpoints

4. Contact Dstl 8 support with the diagnostic information

---

Advanced Configuration

Running Multiple Agents

You can run multiple Dstl 8 agents on the same host by using different cluster names:

# First agent
bash install.sh -p docker \
  --cluster-name docker-host-01 \
  ... -e prod

# Second agent (for a different environment/group)
bash install.sh -p docker \
  --cluster-name docker-host-02 \
  ... -e staging

Custom Docker Configuration

The installation script uses standard Docker commands. For advanced use cases, you can:

Specify Docker Network:

Modify the installation script or run the container with a specific network:

docker network create dstl8-network
# Then modify container creation in the install script

Mount Additional Volumes:

For custom configurations or logs, you can manually adjust volume mounts after reviewing the install script's Docker run command.

---

Container Management

Start/Stop the Agent

Stop the agent:

docker stop <container-id>

Start the agent:

docker start <container-id>

Restart the agent:

docker restart <container-id>

Update the Agent

To update to a newer version:

1. Stop and remove the existing container:

   bash install.sh -o uninstall -p docker

2. Run the installation with the new image tag:

   bash install.sh -p docker \
     --docker-tag v1.4.0 \
     ... (other parameters)

---

Version Information

Current installer version: v1.2.3 Default Docker image: controltheory/supervisor:v1.3.10

To check the installer version:

bash install.sh --version

To view all available options:

bash install.sh --help

To check the running container's image version:

docker inspect <container-id> | grep Image