Deploy Zabbix Proxy with Docker Compose: A Step-by-Step Guide

Serhii Shypylov

08 лют 2025 • 4 min read

Monitoring your IT infrastructure is like keeping an eye on a bustling city—every server, device, and connection needs attention to ensure smooth operations. Zabbix Proxy, paired with Docker Compose, simplifies this by collecting data from remote nodes and sending it to your Zabbix Server, all while running in lightweight containers. In this guide, we’ll walk you through setting up Zabbix Proxy and Zabbix Agent using Docker Compose for efficient, scalable monitoring. Whether you’re managing a distributed network or monitoring devices behind NAT, this setup will save you time and resources.

Why Use Zabbix Proxy with Docker Compose?

Zabbix Proxy acts like a traffic manager, reducing the load on your Zabbix Server by collecting and forwarding data from remote devices. It’s perfect for distributed environments, ensuring reliable monitoring even across complex networks. Docker Compose, on the other hand, streamlines deployment by bundling everything into a single, portable configuration file. This combo offers simplicity, scalability, and isolation—ideal for IT teams looking to monitor smarter, not harder.

Prerequisites for a Smooth Setup

Before diving in, ensure you have the following ready:

Docker and Docker Compose installed on your system.
A working Zabbix Server to connect your proxy to.

Check if Docker is installed:

docker --version
docker-compose --version

If Docker isn’t installed, set it up with:

sudo apt update
sudo apt install docker.io docker-compose -y

Pro Tip: Always verify Docker’s installation to avoid hiccups during deployment. A quick version check saves hours of troubleshooting!

Step-by-Step Guide to Deploy Zabbix Proxy

Follow these steps to get your Zabbix Proxy and Agent up and running in Docker containers.

1. Create a Working Directory

Start by setting up a dedicated folder for your project:

mkdir /opt/zabbix-proxy && cd /opt/zabbix-proxy

This keeps your configuration files organized and easy to manage.

2. Set Up Environment Variables

Create a .env file to store key settings for your Zabbix Proxy and Agent:

vim .env

Add the following configuration:

ZABBIX_VERSION=ubuntu-7.0-latest
ZBX_HOSTNAME=zabbix-proxy
ZBX_SERVER_HOST=zabbix.example.com  # Replace with your Zabbix Server address
ZBX_DEBUGLEVEL=3
ZBX_PROXYMODE=0  # 0 for active proxy, 1 for passive
ZBX_PROXYCONFIGFREQUENCY=60
ZBX_STARTPOLLERS=5
ZBX_STARTPOLLERSUNREACHABLE=3
ZBX_STARTTRAPPERS=5
ZBX_STARTPINGERS=5
ZBX_CACHESIZE=16M
ZBX_HISTORYCACHESIZE=32M
ZBX_HISTORYINDEXCACHESIZE=16M
ZBX_TIMEOUT=4
ZBX_AGENT_HOSTNAME=zabbix-agent
ZBX_AGENT_SERVER=zabbix-proxy
ZBX_AGENT_ACTIVE_SERVER=zabbix-proxy

These variables define how your proxy communicates with the Zabbix Server and how the agent monitors the proxy host itself.

3. Create the Docker Compose File

Next, create a docker-compose.yml file to define your services:

vim docker-compose.yml

Paste the following configuration:

services:
  zabbix-proxy:
    image: zabbix/zabbix-proxy-sqlite3:${ZABBIX_VERSION}
    container_name: zabbix-proxy
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./db_data:/var/lib/zabbix/db_data
      - ./zabbix_proxy_data:/var/lib/zabbix
    ports:
      - "10051:10051"
    networks:
      - zabbix-network
    user: "root"
    dns:
      - 8.8.8.8
      - 1.1.1.1
    healthcheck:
      test: ["CMD-SHELL", "pgrep zabbix_proxy || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

  zabbix-agent:
    image: zabbix/zabbix-agent:${ZABBIX_VERSION}
    container_name: zabbix-agent
    hostname: "monitoring"
    environment:
      ZBX_HOSTNAME: "zabbix-proxy"
      ZBX_DEBUGLEVEL: 4
      ZBX_ENABLEREMOTECOMMANDS: 1
      ZBX_SERVER_HOST: ${ZBX_AGENT_SERVER}
      ZBX_SERVER_ACTIVE: ${ZBX_AGENT_SERVER_ACTIVE}
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/run/docker.sock:/var/run/docker.sock
      - ./zbx_env/etc/zabbix/zabbix_agentd.d:/etc/zabbix/zabbix_agentd.d:ro
      - ./zbx_env/var/lib/zabbix/modules:/var/lib/zabbix/modules:ro
      - ./zbx_env/frontend_hacks:/usr/share/zabbix/local/
      - ./zbx_env/var/lib/zabbix/enc:/var/lib/zabbix/enc:ro
      - ./zbx_env/var/lib/zabbix/ssh_keys:/var/lib/zabbix/ssh_keys:ro
    privileged: true
    depends_on:
      - zabbix-proxy
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pgrep zabbix_agentd || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
    networks:
      - zabbix-network

networks:
  zabbix-network:
    driver: bridge

This file sets up two services: the Zabbix Proxy (using SQLite for lightweight storage) and the Zabbix Agent to monitor the proxy host.

4. Launch the Containers

Run the following command to start your containers in the background:

docker-compose up -d

Verify that both containers are running:

docker ps

Check the logs for any issues:

docker logs -f zabbix-proxy
docker logs -f zabbix-agent

Connecting Zabbix Proxy to Your Zabbix Server

To integrate your proxy with the Zabbix Server, follow these steps in the Zabbix web interface (http://zabbix.example.com):

Add the Proxy:
- Go to Administration → Proxies.
- Click Create Proxy.
- Enter:
  - Name: zabbix-proxy
  - Mode: Match your ZBX_PROXYMODE (Active or Passive).
  - Address: The IP of your proxy server.
- Save your settings.
Assign Devices to the Proxy:
- Navigate to Configuration → Hosts.
- Select a device, set Monitored by proxy to zabbix-proxy, and save.
Monitor the Proxy Host:
- Go to Configuration → Hosts and click Create Host.
- Enter:
  - Name: zabbix-agent
  - Interfaces: Add the agent with the IP of zabbix-agent.
  - Proxy: Select zabbix-proxy.
- Save the configuration.

Verifying Your Setup

To ensure everything is working, reload the Zabbix Server’s configuration cache:

zabbix_proxy -R config_cache_reload

In the Zabbix web interface, check Administration → Proxies. The status for zabbix-proxy should display as OK.

Note: If the status isn’t updating, double-check your ZBX_SERVER_HOST in the .env file and ensure network connectivity between the proxy and server.

Managing Your Containers

Here are some handy commands to manage your setup:

Restart Containers:
```
docker-compose restart
```
Stop Containers:
```
docker-compose down
```

Stop and Remove Data:

docker-compose down -v
rm -rf /opt/zabbix-proxy

Benefits of This Approach

Using Zabbix Proxy with Docker Compose is like packing your monitoring tools into a portable suitcase:

Speed: Deploy in minutes with a single configuration file.
Portability: Run the same setup on any Docker-supported system.
Isolation: Containers keep your proxy separate from other services, reducing conflicts.

This setup is perfect for testing environments or scaling monitoring across distributed networks.

Conclusion: Monitor Smarter with Zabbix and Docker

Setting up Zabbix Proxy with Docker Compose simplifies monitoring for distributed IT environments. By following this guide, you’ve created a lightweight, scalable solution that reduces server load and keeps your infrastructure in check. Ready to take your monitoring to the next level? Explore more Zabbix features or contact our team at x.ai for advanced IT solutions!

🚀 Explore more guides on our blog 👉 blog.1it.pro
📧 Contact us: admin@1it.pro for expert IT guidance.
🌐 Explore more: Visit 1it.pro for top-tier IT solutions.

GitHub

Home