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.

Prerequisites

Before you begin, make sure Docker (1.12.0 or later) is installed on your system. If it is not, follow the Docker installation guide. For Docker Compose deployment, Docker Compose (2.24.0 or later) is also required.

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 based on the latest major versions of the supported operating systems. These images are automatically rebuilt when the underlying OS 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
• centos - CentOS Stream
• ol - Oracle Linux
• ltsc2022 - Windows 11 LTSC 2022 (Zabbix agent only)

Supported <version> values:

• latest - Latest stable Zabbix version on Alpine Linux
• <os>-latest - Latest stable Zabbix version on the selected OS
• <os>-trunk - Latest development (nightly) build on the selected OS
• <os>-X.X-latest - Latest Zabbix minor release of a specific Zabbix major version on the selected OS
• <os>-X.X.* - Specific Zabbix minor release 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 setup—Zabbix server, web interface (running on Nginx), and a database backend (MySQL or PostgreSQL), each running in its own container on Alpine Linux.

# 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

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

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.1 \
  -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 web interface 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–10

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

Deploy Zabbix server (MySQL) with Java gateway

This example shows how to deploy a Zabbix server with a MySQL backend, a Java gateway for JMX monitoring, and an Nginx-based web interface.

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, and use those values in the following steps):

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=utf8mb4 --collation-server=utf8mb4_bin

3. Follow the MySQL logs and wait until MySQL is ready for connections (use Ctrl+C to exit the logs):

docker logs -f mysql-server

# ... [Server] /usr/sbin/mysqld: ready for connections. ...

4. 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

5. Enable log_bin_trust_function_creators in the MySQL server container. This temporarily relaxes security restrictions on stored functions; the setting will be disabled in later steps. It allows the Zabbix database user to create stored functions without the SUPER privilege, which MySQL requires when binary logging is enabled (default since MySQL 8.0). Run the following command:

docker exec -it mysql-server mysql -u root -p'root_pwd' \
  -e "SET GLOBAL log_bin_trust_function_creators = 1;"

6. Run a Zabbix server container and link it to the Java Gateway and MySQL server containers:

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 ZBX_JAVAGATEWAY="zabbix-java-gateway" \
  --network=zabbix-net \
  -p 10051:10051 \
  --restart unless-stopped \
  --init \
  -d zabbix/zabbix-server-mysql:alpine-7.4-latest

7. Follow the Zabbix server logs and wait until Zabbix server has finished initializing the database schema (use Ctrl+C to exit the logs):

docker logs -f zabbix-server-mysql

# ... [info]: ** Creating 'zabbix' schema in MySQL
# ... [info]: ** Database schema successfully created!

8. Disable log_bin_trust_function_creators in the MySQL server container. This re-enforces the security restriction that prevents non-SUPER users from creating stored functions. Run the following command:

docker exec -it mysql-server mysql -u root -p'root_pwd' \
  -e "SET GLOBAL log_bin_trust_function_creators = 0;"

9. Run a Zabbix web interface container and link it to the Zabbix server and MySQL server containers:

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 PHP_TZ="Europe/Riga" \
  --network=zabbix-net \
  -p 80:8080 \
  --restart unless-stopped \
  -d zabbix/zabbix-web-nginx-mysql:alpine-7.4-latest

After the containers are up and running, Zabbix server is started and the web interface is available at http://localhost.

Deploy Zabbix server (PostgreSQL) with SNMP traps

This example shows how to deploy a Zabbix server with a PostgreSQL backend, SNMP traps, and an Nginx-based web interface.

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, and use that value in the following steps):

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 and link it to the PostgreSQL server and SNMP traps containers:

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 \
  --init \
  -d zabbix/zabbix-server-pgsql:alpine-7.4-latest

5. Follow the Zabbix server logs and wait until Zabbix server has finished initializing the database schema (use Ctrl+C to exit the logs):

docker logs -f zabbix-server-pgsql

# ... [info]: ** Creating 'zabbix' schema in PostgreSQL
# ... [info]: ** Database schema successfully created!

6. Run a Zabbix web interface container and link it to the Zabbix server and PostgreSQL server containers:

docker run --name zabbix-web-nginx-pgsql -t \
  -e ZBX_SERVER_HOST="zabbix-server-pgsql" \
  -e DB_SERVER_HOST="postgres-server" \
  -e POSTGRES_DB="zabbix" \
  -e POSTGRES_USER="zabbix" \
  -e POSTGRES_PASSWORD="zabbix_pwd" \
  -e PHP_TZ="Europe/Riga" \
  --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 and running, Zabbix server is started and the web interface is available at http://localhost.

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

This example shows how to deploy a Zabbix server with a MySQL backend, a Java gateway for JMX monitoring, and an Nginx-based web interface, all running on Red Hat Enterprise Linux 8, 9, or 10.

On Red Hat Enterprise Linux, 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, and use those values in the following steps):

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=utf8mb4 --collation-server=utf8mb4_bin

5. Follow the MySQL logs and wait until MySQL is ready for connections (use Ctrl+C to exit the logs):

podman logs -f mysql-server

# ... [Server] /usr/sbin/mysqld: ready for connections. ...

6. 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

7. Enable log_bin_trust_function_creators in the MySQL server container. This temporarily relaxes security restrictions on stored functions; the setting will be disabled in later steps. It allows the Zabbix database user to create stored functions without the SUPER privilege, which MySQL requires when binary logging is enabled (default since MySQL 8.0). Run the following command:

podman exec -it mysql-server mysql -u root -p'root_pwd' \
  -e "SET GLOBAL log_bin_trust_function_creators = 1;"

8. Run a Zabbix server container and link it to the Java Gateway and MySQL server containers:

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 ZBX_JAVAGATEWAY="127.0.0.1" \
  --restart=always \
  --init \
  --pod=zabbix \
  -d registry.connect.redhat.com/zabbix/zabbix-server-mysql-74

9. Follow the Zabbix server logs and wait until Zabbix server has finished initializing the database schema (use Ctrl+C to exit the logs):

podman logs -f zabbix-server-mysql

# ... [info]: ** Creating 'zabbix' schema in MySQL
# ... [info]: ** Database schema successfully created!

10. Disable log_bin_trust_function_creators in the MySQL server container. This re-enforces the security restriction that prevents non-SUPER users from creating stored functions. Run the following command:

podman exec -it mysql-server mysql -u root -p'root_pwd' \
  -e "SET GLOBAL log_bin_trust_function_creators = 0;"

11. Run a Zabbix web interface container and link it to the Zabbix server and MySQL server containers:

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 PHP_TZ="Europe/Riga" \
  --restart=always \
  --pod=zabbix \
  -d registry.connect.redhat.com/zabbix/zabbix-web-mysql-74

After the containers are up and running, Zabbix server is started and the web interface is available at http://localhost.