---
title: "Docker"
description: "Deploy Middleware Monitoring Agent in Docker containers to enable deep infrastructure insights and streamlined observability."
section: "Agent Installation"
breadcrumb: "Containers > Docker"
canonical: "https://docs.middleware.io/get-started/agent/docker"
---
# Docker

The Middleware Infrastructure Agent can run as a Docker container to collect host metrics, container metrics, and configured logs from your Docker environment.

Use the collected CPU, memory, network, and container-status data to investigate resource usage and unhealthy containers without installing the Agent directly on the host operating system.

## How it works

The Middleware Infrastructure Agent runs as a container on your Docker host and collects telemetry using:

- **Docker daemon**: Collects container information and resource metrics through the Docker API.
- **Host filesystem mounts**: Accesses host and container information required for monitoring.
- **Log collection**: Collects container logs through configured host volume mounts.
- **Telemetry endpoints**: Exposes ports 9319 and 9320 for receiving OpenTelemetry data.

You can install the Agent using the installation script or Docker Compose.

## Prerequisites

Before installing the Middleware Docker Agent, verify the following requirements:

**Note**: Run only one Middleware Infrastructure Agent per Docker host to avoid duplicate telemetry collection and configuration conflicts.

## Installation

#### 1 Get your Middleware credentials

1. Log in to your [Middleware account](https://app.middleware.io/auth/login).
2. Go to [Installation → Docker](https://app.middleware.io/installation/agent/docker).
3. Copy the installation command containing your API key and target URL.

Alternatively, use the following command and replace the placeholders with your account details.

#### 2 Install the Docker Agent

Run the following command on your Docker host:

```bash
MW_API_KEY="<MW_API_KEY>" \
MW_TARGET="https://<MW_UID>.middleware.io:443" \
bash -c "$(curl -fsSL https://install.middleware.io/scripts/docker-install.sh)"
```

The installation script deploys the Middleware Infrastructure Agent as a Docker container.

Replace:

| Variable | Description |
| --- | --- |
| `MW_API_KEY` | Your Middleware API key |
| `MW_TARGET` | Your Middleware target URL, including port 443 |

#### 3 Add custom host tags (optional)

To associate custom tags with your Docker host, set the `MW_HOST_TAGS` environment variable during installation.

Specify multiple tags as comma-separated `key:value` pairs.

```bash
MW_HOST_TAGS=env:prod,role:web \
MW_API_KEY="<MW_API_KEY>" \
MW_TARGET="https://<MW_UID>.middleware.io:443" \
bash -c "$(curl -L https://install.middleware.io/scripts/docker-install.sh)"
```

After installation, verify the configured tags in the Middleware UI:

**Infrastructure → [Your Host] → System Information**

#### 4 Verify the Agent installation

Check whether the Middleware Agent container was created and is running:

```bash
docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master
```

Check the container status:

- `Up` — The Agent container is running.
- `Exited` — The Agent container was created but is no longer running. Check its logs to identify the issue.
- **Blank output** — No matching Agent container was found. Review the installation output for errors.

If the container is not running, check its logs:

```bash
docker logs <container_id>
```

#### 5 Verify data collection

After the Agent is running:

1. Log in to Middleware.
2. Go to [Infrastructure Monitoring → Hosts](https://app.middleware.io/infrastructure/host).
3. Verify that your Docker host appears with a recent Last Seen timestamp.
4. Open **[Infrastructure Monitoring → Containers](https://app.middleware.io/infrastructure/container/)** to view collected container metrics.

Data typically starts appearing within a few minutes after installation.

After data collection starts, you can:

- View host and container metrics in [Infrastructure Monitoring](https://docs.middleware.io/features/infrastructure/hosts).
- View collected container logs in [Log Monitoring](https://docs.middleware.io/features/logs/explorer).
- [Create alerts](https://docs.middleware.io/features/alerts/manage-alerts) for CPU, memory, network usage, and other collected metrics.
- [Create custom dashboards](https://docs.middleware.io/features/dashboards/builder) to monitor Docker container performance.

## Install using Docker Compose

You can also deploy the Middleware Infrastructure Agent using Docker Compose.

Use this method if you manage Docker services through Compose files or want to configure the Agent's ports, volumes, and restart policy directly.

#### 1 Create a Docker Compose file

Create a file named `docker-compose.yml` and add the following configuration:

```yml
version: "3.8"

services:
  mw-host-agent:
    image: ghcr.io/middleware-labs/mw-host-agent:master
    restart: unless-stopped
    environment:
      - MW_API_KEY=<MW_API_KEY>
      - MW_TARGET=https://<MW_UID>.middleware.io:443
    ports:
      - "9319:9319"
      - "9320:9320"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /proc:/host/proc:ro
      - /sys/fs/cgroup:/host/sys/fs/cgroup:ro
```

Replace `MW_API_KEY` and `MW_TARGET` with your Middleware account details.

#### Configuration reference

| Configuration | Description |
| --- | --- |
| `image` | Middleware Infrastructure Agent container image |
| `restart: unless-stopped` | Restarts the Agent automatically unless manually stopped |
| `MW_API_KEY` | Middleware API key |
| `MW_TARGET` | Middleware target URL |
| `9319` | OTLP/gRPC endpoint |
| `9320` | OTLP/HTTP endpoint |
| `/var/run/docker.sock` | Provides access to the Docker daemon |
| `/proc` | Provides host process and system information |
| `/sys/fs/cgroup` | Provides container resource and cgroup information |

**Note**: Mounting the Docker socket provides the Agent with access to the Docker API. Restrict access to the Agent configuration and container runtime accordingly.

#### 2 Start the Agent

From the directory containing docker-compose.yml, run:

```bash
docker compose up -d
```

Verify the container status:

```bash
docker compose ps
```

The `mw-host-agent` service should show a running status.

#### 3 Verify data collection

Go to [**Infrastructure Monitoring → Hosts**](https://app.middleware.io/infrastructure/host) and verify that the Docker host is reporting data.

You can also check container-level metrics under **[Infrastructure Monitoring → Containers](https://app.middleware.io/infrastructure/container/)**.

## Troubleshooting

If the Agent is installed but telemetry does not appear in Middleware, check the following.

### Docker socket not found

If the Agent reports:

```
Error: no such file or directory: /var/run/docker.sock
```

Verify that:

- Docker Engine is installed and running.
- The Docker socket exists at `/var/run/docker.sock`.
- The Docker socket path has not been customized using `DOCKER_HOST`.
- The Agent has access to the configured Docker socket.

### Permission denied on mounted volumes

If the Agent cannot access required host files or Docker resources:

- Verify that the user running the installation has sufficient permissions.
- Check permissions for the Docker socket and mounted directories.
- Run the installation with the required privileges.

Avoid changing host filesystem permissions broadly to resolve mount errors.

### No metrics in Middleware

If the Agent is running but metrics are not available:

- **Check network connectivity**: Verify that outbound HTTPS traffic to `MW_TARGET` on port `443` is allowed.
- **Check API key**: Confirm that `MW_API_KEY` is valid and configured correctly.
- **Check duplicate Agents**: Make sure only one Middleware Infrastructure Agent is running per host.
- **Check proxy settings**: If the host uses a corporate proxy, configure `HTTP_PROXY` and `HTTPS_PROXY` as required.
- **Check Agent logs**: Review the container logs for collection or connectivity errors.

### Agent container exits immediately

If the Agent container stops after installation, run:

```bash
docker logs <container_id>
```

Check the logs for:

- Missing or invalid environment variables.
- Network connectivity errors.
- Docker socket or volume mount permission errors.
- Agent initialization failures.

Resolve the reported error and restart the Agent.

## Uninstall

To remove the Middleware Infrastructure Agent installed using the Docker installation script, identify the Agent container:

```bash
docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master
```

Stop the Agent container:

```bash
docker stop $(docker ps -a -q --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master)
```

Remove the container:

```bash
docker rm $(docker ps -a -q --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master)
```

**Note**: These commands target containers using the specified Middleware Agent image. Verify the matching containers before removing them.

### Uninstall Docker Compose deployment

If you installed the Agent using Docker Compose, run the following command from the directory containing `docker-compose.yml`:

```bash
docker compose down
```

This stops and removes the services and networks created by that Compose project.

## Collected metrics

The Middleware Docker Agent collects container metrics across the following categories:

| Category | Example metrics | Description |
| --- | --- | --- |
| CPU | `container.cpu.utilization`, `container.cpu.usage.total` | CPU utilization and usage |
| Memory | `container.memory.usage.total`, `container.memory.percent` | Memory consumption and utilization |
| Network | `container.network.io.usage.rx_bytes`, `container.network.io.usage.tx_bytes` | Network traffic and packet statistics |
| Disk I/O | `container.blockio.io_service_bytes_recursive` | Container disk I/O activity |
| Processes | `container.pids.count`, `container.pids.limit` | Process count and configured limits |
| Container status | `container.status`, `container.uptime` | Container state and uptime |
| Restarts | `container.restarts` | Number of container restarts |

**Note**: Some metrics are available only with specific cgroup versions. For example, several Block I/O and memory metrics require cgroups v1, while others require cgroups v2.

For the complete list of supported metrics, retain the existing **Collected Metrics** reference table.

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us page or join our Slack channel.