5 Installation from containers

Overview

This page describes how to deploy Zabbix using Docker or Docker Compose.

Docker Compose is the quickest way to deploy Zabbix. It reads a configuration file and automatically starts all the containers that make up a complete Zabbix setup, in the correct order.

Docker (manual deployment) achieves the same result by deploying each component step by step, which may suit users already managing an existing Docker environment.

Prerequisites

Before you begin, make sure Docker is installed on your system. If it is not, follow the Docker installation guide.

Some Zabbix components require specific ports to be open on the host running Docker (e.g., 10051/TCP for Zabbix server, 162/UDP for SNMP traps). See Requirements for a full list of ports used by Zabbix components. For Zabbix server and agent, the default port can be changed by setting the ZBX_LISTENPORT environment variable on the respective container.

Available Docker images

Zabbix provides a Docker image for each Zabbix component, all published on Docker Hub. Each image is used to create a container running that component.

All Zabbix component images on Docker Hub are automatically rebuilt when their base images are updated.

Image tags

Each image supports tags to select the base operating system and Zabbix version:

zabbix/<image>:<os>-<version>

Supported <os> values:

• alpine - Alpine Linux
• ubuntu - Ubuntu
• ol - Oracle Linux
• ltsc2019 - Windows 10 LTSC 2019 (Zabbix agent only)
• ltsc2022 - Windows 11 LTSC 2022 (Zabbix agent only)

Supported <version> values:

• latest - Latest stable version on Alpine Linux
• <os>-latest - Latest stable version on the selected OS
• <os>-trunk - Latest development (nightly) build on the selected OS
• <os>-X.X-latest - Latest minor release of a specific major version on the selected OS
• <os>-X.X.* - Specific minor version on the selected OS

Examples:

# Latest stable Zabbix proxy (SQLite3) on Alpine Linux:
docker pull zabbix/zabbix-proxy-sqlite3:latest

# Latest stable Zabbix proxy (SQLite3) on Ubuntu:
docker pull zabbix/zabbix-proxy-sqlite3:ubuntu-latest

# Latest development (nightly) build of Zabbix server (MySQL) on Ubuntu:
docker pull zabbix/zabbix-server-mysql:ubuntu-trunk

# Latest 7.4 minor release of Zabbix server (MySQL) on Alpine Linux:
docker pull zabbix/zabbix-server-mysql:alpine-7.4-latest

# Version 7.4.1 of Zabbix server (MySQL) on Alpine Linux:
docker pull zabbix/zabbix-server-mysql:alpine-7.4.1

Docker Compose

Docker Compose is the quickest way to deploy Zabbix. It reads a configuration file (Compose file) and handles the entire setup—pulling Docker images, creating an internal network between containers, setting up storage, initializing the database, and starting everything in the correct order.

The official Zabbix Dockerfiles repository provides ready-to-use Docker Compose files and an .env-based configuration system supporting different operating systems, database backends, and Zabbix component configuration.

1. Clone the repository, navigate to it, and switch to version 7.4:

git clone https://github.com/zabbix/zabbix-docker.git
cd zabbix-docker
git checkout 7.4

2. (Optional) Customize the deployment with environment variables. This step can be skipped for a default setup.

3. Deploy the default Zabbix setup:

# With MySQL as the database:
docker compose -f ./compose.yaml up -d

# With PostgreSQL as the database:
docker compose -f ./compose_pgsql.yaml up -d

This starts Zabbix server, web interface (running on Nginx), and a database backend (MySQL or PostgreSQL), each running in its own container on Alpine Linux (default). After the containers are up un running (typically within 1–3 minutes), Zabbix server is started and the web interface is available at http://localhost.

You can check that everything is working with the following command:

docker compose ps

All containers should show a running status. If any show exited, check their logs (docker logs <container-name>).

Environment variables

Docker Compose behavior and Zabbix component configuration can both be customized using environment variables.

Compose-level variables (defined in the .env file) control which Docker images, ports, and network IP ranges are used. You can use these variables inline before the docker compose command, or edit the .env file.

For example, the following command deploys a complete multi-container Zabbix setup using an Ubuntu-based image (instead of the default Alpine Linux) and exposing the web interface via Nginx on custom HTTP (8282) and HTTPS (8443) ports:

OS=ubuntu \
ZABBIX_WEB_NGINX_HTTP_PORT=8282 \
ZABBIX_WEB_NGINX_HTTPS_PORT=8443 \
docker compose -f ./compose.yaml up -d

Component-level variables (defined in the env_vars/.env_<component> files) control Zabbix component configuration. Edit the respective .env_<component> file before running the docker compose command.

For example, you can adjust Zabbix server passive poller count and cache settings, as well as configure the web interface timezone by editing the following variables:

# env_vars/.env_srv
ZBX_STARTPOLLERS=20
ZBX_CACHESIZE=64M
ZBX_HISTORYCACHESIZE=32M

# env_vars/.env_web
PHP_TZ=Europe/Paris

Volumes

Docker Compose stores persistent data in the zbx_env/ directory created alongside the Compose file. This directory preserves component data across container restarts and updates.

The contents of zbx_env/ are pre-defined for each component's image. For example:

• zbx_env/etc/ - used by the Zabbix web interface container
• zbx_env/usr/ and zbx_env/var/ - used by the Zabbix server container

For more information on each volume, see the Allowed volumes section in each component's Docker image description on Docker Hub.

Makefile

The Zabbix Dockerfiles repository also provides a Makefile as a shortcut for common Docker Compose tasks. Instead of using the full docker compose command, you can use shorter make commands (run make help to see the available options):

# Default deployment (Zabbix server, web interface, MySQL, all on Alpine Linux)
make up

# Custom deployment (Zabbix server, web interface with custom Nginx ports, PostgreSQL, all on Ubuntu)
make up \
  OS=ubuntu \
  DB=pgsql \
  ZABBIX_WEB_NGINX_HTTP_PORT=8282 \
  ZABBIX_WEB_NGINX_HTTPS_PORT=8443

By default, make up starts only a minimal set of services (Zabbix server, web interface, and database). This keeps the setup lightweight and avoids starting components that may not be needed. To include additional components, you can use the following Compose profiles:

# Default deployment + Zabbix agent, Java gateway, web service, and SNMP traps:
make up COMPOSE_PROFILES=full

# COMPOSE_PROFILES=full + Zabbix proxy (MySQL and SQLite3):
make up COMPOSE_PROFILES=all

Docker (manual deployment)

Use manual deployment when you want to deploy Zabbix step by step, run individual components, integrate them with an existing environment, or use an alternative container runtime such as Podman.

For example, to deploy a Zabbix proxy, run the following command:

docker run --name zabbix-proxy-sqlite3 \
  -e ZBX_SERVER_HOST=192.0.2.0 \
  -e ZBX_PROXYMODE=0 \
  -e ZBX_HOSTNAME=zabbix-proxy-sqlite3 \
  -v zabbix-proxy-data:/var/lib/zabbix/db_data \
  --init \
  -d \
  zabbix/zabbix-proxy-sqlite3:alpine-7.4-latest

This command:

• Pulls the zabbix/zabbix-proxy-sqlite3:alpine-7.4-latest Docker image.

• Creates and starts a zabbix-proxy-sqlite3 container based on the Docker image (with --init and -d flags).

• Configures the Zabbix proxy Server parameter via the ZBX_SERVER_HOST environment variable. This parameter specifies the IP address of the Zabbix server from which the proxy will retrieve configuration data and to which it will send collected data. Note that other variables required for active proxy operation use default values and can be omitted.

• Connects a storage location managed by Docker (e.g., /var/lib/docker/volumes/zabbix-proxy-data/) to the container's /var/lib/zabbix directory so that Zabbix proxy data is stored permanently, even if the container is removed.

After deploying the Zabbix proxy container, you can proceed to add the proxy in your Zabbix frontend and configure hosts to be monitored by this proxy.

The examples below cover three additional deployment scenarios:

• Zabbix server (MySQL) with Java gateway
• Zabbix server (PostgreSQL) with SNMP traps
• Zabbix server (MySQL) with Java gateway on RHEL 8

For more examples, please refer to each component's Docker image description on Docker Hub.

Deploy Zabbix server (MySQL) with Java gateway

1. Create a dedicated Docker network, so that all Zabbix component containers can reach each other by container name:

docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 zabbix-net

2. Run an empty MySQL server container (replace zabbix_pwd and root_pwd with strong passwords):

docker run --name mysql-server -t \
  -e MYSQL_DATABASE="zabbix" \
  -e MYSQL_USER="zabbix" \
  -e MYSQL_PASSWORD="zabbix_pwd" \
  -e MYSQL_ROOT_PASSWORD="root_pwd" \
  --network=zabbix-net \
  --restart unless-stopped \
  -d mysql:8.0-oracle \
  --character-set-server=utf8 --collation-server=utf8_bin \
  --default-authentication-plugin=mysql_native_password \
  --innodb-default-row-format=dynamic \
  --innodb-strict-mode=OFF

3. Run a Zabbix Java gateway container:

docker run --name zabbix-java-gateway -t \
  --network=zabbix-net \
  --restart unless-stopped \
  -d zabbix/zabbix-java-gateway:alpine-7.4-latest

4. Run a Zabbix server container and link it to the MySQL server container (replace zabbix_pwd and root_pwd with the same passwords used in step 2):

docker run --name zabbix-server-mysql -t \
  -e DB_SERVER_HOST="mysql-server" \
  -e MYSQL_DATABASE="zabbix" \
  -e MYSQL_USER="zabbix" \
  -e MYSQL_PASSWORD="zabbix_pwd" \
  -e MYSQL_ROOT_PASSWORD="root_pwd" \
  -e ZBX_JAVAGATEWAY="zabbix-java-gateway" \
  --network=zabbix-net \
  -p 10051:10051 \
  --restart unless-stopped \
  -d zabbix/zabbix-server-mysql:alpine-7.4-latest

5. Run a Zabbix web interface container and link to the Zabbix server and MySQL server containers (replace zabbix_pwd and root_pwd with the same passwords used in step 2):

docker run --name zabbix-web-nginx-mysql -t \
  -e ZBX_SERVER_HOST="zabbix-server-mysql" \
  -e DB_SERVER_HOST="mysql-server" \
  -e MYSQL_DATABASE="zabbix" \
  -e MYSQL_USER="zabbix" \
  -e MYSQL_PASSWORD="zabbix_pwd" \
  -e MYSQL_ROOT_PASSWORD="root_pwd" \
  --network=zabbix-net \
  -p 80:8080 \
  --restart unless-stopped \
  -d zabbix/zabbix-web-nginx-mysql:alpine-7.4-latest

After the containers are up un running (typically within 1–3 minutes), Zabbix server is started and the web interface is available at http://localhost.

Deploy Zabbix server (PostgreSQL) with SNMP traps

1. Create a dedicated Docker network, so that all Zabbix component containers can reach each other by container name:

docker network create --subnet 172.20.0.0/16 --ip-range 172.20.240.0/20 zabbix-net

2. Run an empty PostgreSQL server container (replace zabbix_pwd with a strong password):

docker run --name postgres-server -t \
  -e POSTGRES_USER="zabbix" \
  -e POSTGRES_PASSWORD="zabbix_pwd" \
  -e POSTGRES_DB="zabbix" \
  --network=zabbix-net \
  --restart unless-stopped \
  -d postgres:latest

3. Run a Zabbix SNMP traps container:

docker run --name zabbix-snmptraps -t \
  -v /zbx_instance/snmptraps:/var/lib/zabbix/snmptraps:rw \
  -v /var/lib/zabbix/mibs:/usr/share/snmp/mibs:ro \
  --network=zabbix-net \
  -p 162:1162/udp \
  --restart unless-stopped \
  -d zabbix/zabbix-snmptraps:alpine-7.4-latest

4. Run a Zabbix server container, link it to the PostgreSQL server container and SNMP traps container (replace zabbix_pwd with the same password used in step 2):

docker run --name zabbix-server-pgsql -t \
  -e DB_SERVER_HOST="postgres-server" \
  -e POSTGRES_USER="zabbix" \
  -e POSTGRES_PASSWORD="zabbix_pwd" \
  -e POSTGRES_DB="zabbix" \
  -e ZBX_ENABLE_SNMP_TRAPS="true" \
  --network=zabbix-net \
  -p 10051:10051 \
  --volumes-from zabbix-snmptraps \
  --restart unless-stopped \
  -d zabbix/zabbix-server-pgsql:alpine-7.4-latest

5. Run a Zabbix web interface container and link it to the Zabbix server and PostgreSQL server containers (replace zabbix_pwd with the same password used in step 2):

docker run --name zabbix-web-nginx-pgsql -t \
  -e ZBX_SERVER_HOST="zabbix-server-pgsql" \
  -e DB_SERVER_HOST="postgres-server" \
  -e POSTGRES_USER="zabbix" \
  -e POSTGRES_PASSWORD="zabbix_pwd" \
  -e POSTGRES_DB="zabbix" \
  --network=zabbix-net \
  -p 443:8443 \
  -p 80:8080 \
  -v /etc/ssl/nginx:/etc/ssl/nginx:ro \
  --restart unless-stopped \
  -d zabbix/zabbix-web-nginx-pgsql:alpine-7.4-latest

After the containers are up un running (typically within 1–3 minutes), Zabbix server is started and the web interface is available at http://localhost.

Deploy Zabbix server (MySQL) with Java gateway on RHEL 8

On Red Hat Enterprise Linux 8, the recommended container runtime is Podman instead of Docker. Podman works similarly to Docker but does not require a background service running as root, which makes it a better fit for Red Hat environments.

1. Create a new pod with the name zabbix and exposed ports for Zabbix web interface and Zabbix server trapper:

podman pod create --name zabbix -p 80:8080 -p 10051:10051

2. (Optional) Run a Zabbix agent container in the zabbix pod location:

podman run --name zabbix-agent \
  -e ZBX_SERVER_HOST="127.0.0.1,localhost" \
  --restart=always \
  --pod=zabbix \
  -d registry.connect.redhat.com/zabbix/zabbix-agent-74:latest

3. Create a ./mysql/ directory on the RHEL host:

mkdir -p ./mysql

4. Run an empty MySQL server container (replace zabbix_pwd and root_pwd with strong passwords):

podman run --name mysql-server -t \
  -e MYSQL_DATABASE="zabbix" \
  -e MYSQL_USER="zabbix" \
  -e MYSQL_PASSWORD="zabbix_pwd" \
  -e MYSQL_ROOT_PASSWORD="root_pwd" \
  -v ./mysql/:/var/lib/mysql/:Z \
  --restart=always \
  --pod=zabbix \
  -d mysql:8.0 \
  --character-set-server=utf8 --collation-server=utf8_bin \
  --default-authentication-plugin=mysql_native_password \
  --innodb-default-row-format=dynamic \
  --innodb-strict-mode=OFF

5. Run a Zabbix Java gateway container:

podman run --name zabbix-java-gateway -t \
  --restart=always \
  --pod=zabbix \
  -d registry.connect.redhat.com/zabbix/zabbix-java-gateway-74

6. Run a Zabbix server container (replace zabbix_pwd and root_pwd with the same passwords used in step 4):

podman run --name zabbix-server-mysql -t \
  -e DB_SERVER_HOST="127.0.0.1" \
  -e MYSQL_DATABASE="zabbix" \
  -e MYSQL_USER="zabbix" \
  -e MYSQL_PASSWORD="zabbix_pwd" \
  -e MYSQL_ROOT_PASSWORD="root_pwd" \
  -e ZBX_JAVAGATEWAY="127.0.0.1" \
  --restart=always \
  --pod=zabbix \
  -d registry.connect.redhat.com/zabbix/zabbix-server-mysql-74

7. Run a Zabbix web interface container (replace zabbix_pwd and root_pwd with the same passwords used in step 4):

podman run --name zabbix-web-mysql -t \
  -e ZBX_SERVER_HOST="127.0.0.1" \
  -e DB_SERVER_HOST="127.0.0.1" \
  -e MYSQL_DATABASE="zabbix" \
  -e MYSQL_USER="zabbix" \
  -e MYSQL_PASSWORD="zabbix_pwd" \
  -e MYSQL_ROOT_PASSWORD="root_pwd" \
  --restart=always \
  --pod=zabbix \
  -d registry.connect.redhat.com/zabbix/zabbix-web-mysql-74