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.

Since Zabbix 6.0, deterministic triggers need to be created during the installation. If binary logging is enabled for MySQL/MariaDB, this requires superuser privileges or setting the variable/configuration parameter log_bin_trust_function_creators = 1. See Database creation scripts for instructions how to set the variable.

Note that if executing from a console, the variable will only be set temporarily and will be dropped when a Docker is restarted. In this case, keep your SQL service running, only stop zabbix-server service by running docker compose down zabbix-server and then docker compose up -d zabbix-server.

Alternatively, you can set this variable in the configuration file.

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.

Structure

All Zabbix components are available in the following Docker repositories:

Additionally there is SNMP trap support. It is provided as additional repository (zabbix/zabbix-snmptraps) based on Ubuntu Trusty only. It could be linked with Zabbix server and Zabbix proxy.

Versions

Each repository of Zabbix components contains the following tags:

  • latest - latest stable version of a Zabbix component based on Alpine Linux image
  • alpine-latest - latest stable version of a Zabbix component based on Alpine Linux image
  • ubuntu-latest - latest stable version of a Zabbix component based on Ubuntu image
  • alpine-5.4-latest - latest minor version of a Zabbix 5.4 component based on Alpine Linux image
  • ubuntu-5.4-latest - latest minor version of a Zabbix 5.4 component based on Ubuntu image
  • alpine-5.4.* - different minor versions of a Zabbix 5.4 component based on Alpine Linux image, where * is the minor version of Zabbix component
  • ubuntu-5.4.* - different minor versions of a Zabbix 5.4 component based on Ubuntu image, where * is the minor version of Zabbix component

Docker Compose

Zabbix provides compose files also for defining and running multi-container Zabbix components in Docker. These compose files are available in Zabbix docker official repository on github.com: https://github.com/zabbix/zabbix-docker. These compose files are added as examples, they are overloaded. For example, they contain proxies with MySQL and SQLite3 support.

There are a few different versions of compose files:
File name Description
docker-compose_v3_alpine_mysql_latest.yaml The compose file runs the latest version of Zabbix 5.4 components on Alpine Linux with MySQL database support.
docker-compose_v3_alpine_mysql_local.yaml The compose file locally builds the latest version of Zabbix 5.4 and runs Zabbix components on Alpine Linux with MySQL database support.
docker-compose_v3_alpine_pgsql_latest.yaml The compose file runs the latest version of Zabbix 5.4 components on Alpine Linux with PostgreSQL database support.
docker-compose_v3_alpine_pgsql_local.yaml The compose file locally builds the latest version of Zabbix 5.4 and runs Zabbix components on Alpine Linux with PostgreSQL database support.
docker-compose_v3_centos_mysql_latest.yaml The compose file runs the latest version of Zabbix 5.4 components on CentOS 8 with MySQL database support.
docker-compose_v3_centos_mysql_local.yaml The compose file locally builds the latest version of Zabbix 5.4 and runs Zabbix components on CentOS 8 with MySQL database support.
docker-compose_v3_centos_pgsql_latest.yaml The compose file runs the latest version of Zabbix 5.4 components on CentOS 8 with PostgreSQL database support.
docker-compose_v3_centos_pgsql_local.yaml The compose file locally builds the latest version of Zabbix 5.4 and runs Zabbix components on CentOS 8 with PostgreSQL database support.
docker-compose_v3_ubuntu_mysql_latest.yaml The compose file runs the latest version of Zabbix 5.4 components on Ubuntu 20.04 with MySQL database support.
docker-compose_v3_ubuntu_mysql_local.yaml The compose file locally builds the latest version of Zabbix 5.4 and runs Zabbix components on Ubuntu 20.04 with MySQL database support.
docker-compose_v3_ubuntu_pgsql_latest.yaml The compose file runs the latest version of Zabbix 5.4 components on Ubuntu 20.04 with PostgreSQL database support.
docker-compose_v3_ubuntu_pgsql_local.yaml The compose file locally builds the latest version of Zabbix 5.4 and runs Zabbix components on Ubuntu 20.04 with PostgreSQL database support.

Available Docker compose files support version 3 of Docker Compose.

Environment variables

All Zabbix component images provide environment variables to control configuration. These environment variables are listed in each component repository. These environment variables are options from Zabbix configuration files, but with different naming method. For example, ZBX_LOGSLOWQUERIES is equal to LogSlowQueries from Zabbix server and Zabbix proxy configuration files.

Some of configuration options are not allowed to change. For example, PIDFile and LogType.

Some of components have specific environment variables, which do not exist in official Zabbix configuration files:
Variable Components Description
DB_SERVER_HOST Server
Proxy
Web interface		 This variable is IP or DNS name of MySQL or PostgreSQL server.
By default, value is mysql-server or postgres-server for MySQL or PostgreSQL respectively
DB_SERVER_PORT Server
Proxy
Web interface		 This variable is port of MySQL or PostgreSQL server.
By default, value is '3306' or '5432' respectively.
MYSQL_USER Server
Proxy
Web-interface		 MySQL database user.
By default, value is 'zabbix'.
MYSQL_PASSWORD Server
Proxy
Web interface		 MySQL database password.
By default, value is 'zabbix'.
MYSQL_DATABASE Server
Proxy
Web interface		 Zabbix database name.
By default, value is 'zabbix' for Zabbix server and 'zabbix_proxy' for Zabbix proxy.
POSTGRES_USER Server
Web interface		 PostgreSQL database user.
By default, value is 'zabbix'.
POSTGRES_PASSWORD Server
Web interface		 PostgreSQL database password.
By default, value is 'zabbix'.
POSTGRES_DB Server
Web interface		 Zabbix database name.
By default, value is 'zabbix' for Zabbix server and 'zabbix_proxy' for Zabbix proxy.
PHP_TZ Web-interface Timezone in PHP format. Full list of supported timezones are available on php.net.
By default, value is 'Europe/Riga'.
ZBX_SERVER_NAME Web interface Visible Zabbix installation name in right top corner of the web interface.
By default, value is 'Zabbix Docker'
ZBX_JAVAGATEWAY_ENABLE Server
Proxy		 Enables communication with Zabbix Java gateway to collect Java related checks.
By default, value is "false"
ZBX_ENABLE_SNMP_TRAPS Server
Proxy		 Enables SNMP trap feature. It requires zabbix-snmptraps instance and shared volume /var/lib/zabbix/snmptraps to Zabbix server or Zabbix proxy.
Volumes

The images allow to use some mount points. These mount points are different and depend on Zabbix component type:
Volume Description
Zabbix agent
/etc/zabbix/zabbix_agentd.d The volume allows to include *.conf files and extend Zabbix agent using the UserParameter feature
/var/lib/zabbix/modules The volume allows to load additional modules and extend Zabbix agent using the LoadModule feature
/var/lib/zabbix/enc The volume is used to store TLS-related files. These file names are specified using ZBX_TLSCAFILE, ZBX_TLSCRLFILE, ZBX_TLSKEY_FILE and ZBX_TLSPSKFILE environment variables
Zabbix server
/usr/lib/zabbix/alertscripts The volume is used for custom alert scripts. It is the AlertScriptsPath parameter in zabbix_server.conf
/usr/lib/zabbix/externalscripts The volume is used by external checks. It is the ExternalScripts parameter in zabbix_server.conf
/var/lib/zabbix/modules The volume allows to load additional modules and extend Zabbix server using the LoadModule feature
/var/lib/zabbix/enc The volume is used to store TLS related files. These file names are specified using ZBX_TLSCAFILE, ZBX_TLSCRLFILE, ZBX_TLSKEY_FILE and ZBX_TLSPSKFILE environment variables
/var/lib/zabbix/ssl/certs The volume is used as location of SSL client certificate files for client authentication. It is the SSLCertLocation parameter in zabbix_server.conf
/var/lib/zabbix/ssl/keys The volume is used as location of SSL private key files for client authentication. It is the SSLKeyLocation parameter in zabbix_server.conf
/var/lib/zabbix/ssl/ssl_ca The volume is used as location of certificate authority (CA) files for SSL server certificate verification. It is the SSLCALocation parameter in zabbix_server.conf
/var/lib/zabbix/snmptraps The volume is used as location of snmptraps.log file. It could be shared by zabbix-snmptraps container and inherited using the volumes_from Docker option while creating a new instance of Zabbix server. SNMP trap processing feature could be enabled by using shared volume and switching the ZBX_ENABLE_SNMP_TRAPS environment variable to 'true'
/var/lib/zabbix/mibs The volume allows to add new MIB files. It does not support subdirectories, all MIBs must be placed in /var/lib/zabbix/mibs
Zabbix proxy
/usr/lib/zabbix/externalscripts The volume is used by external checks. It is the ExternalScripts parameter in zabbix_proxy.conf
/var/lib/zabbix/modules The volume allows to load additional modules and extend Zabbix server using the LoadModule feature
/var/lib/zabbix/enc The volume is used to store TLS related files. These file names are specified using ZBX_TLSCAFILE, ZBX_TLSCRLFILE, ZBX_TLSKEY_FILE and ZBX_TLSPSKFILE environment variables
/var/lib/zabbix/ssl/certs The volume is used as location of SSL client certificate files for client authentication. It is the SSLCertLocation parameter in zabbix_proxy.conf
/var/lib/zabbix/ssl/keys The volume is used as location of SSL private key files for client authentication. It is the SSLKeyLocation parameter in zabbix_proxy.conf
/var/lib/zabbix/ssl/ssl_ca The volume is used as location of certificate authority (CA) files for SSL server certificate verification. It is the SSLCALocation parameter in zabbix_proxy.conf
/var/lib/zabbix/snmptraps The volume is used as location of snmptraps.log file. It could be shared by the zabbix-snmptraps container and inherited using the volumes_from Docker option while creating a new instance of Zabbix server. SNMP trap processing feature could be enabled by using shared volume and switching the ZBX_ENABLE_SNMP_TRAPS environment variable to 'true'
/var/lib/zabbix/mibs The volume allows to add new MIB files. It does not support subdirectories, all MIBs must be placed in /var/lib/zabbix/mibs
Zabbix web interface based on Apache2 web server
/etc/ssl/apache2 The volume allows to enable HTTPS for Zabbix web interface. The volume must contain the two ssl.crt and ssl.key files prepared for Apache2 SSL connections
Zabbix web interface based on Nginx web server
/etc/ssl/nginx The volume allows to enable HTTPS for Zabbix web interface. The volume must contain the two ssl.crt, ssl.key files and dhparam.pem prepared for Nginx SSL connections
Zabbix snmptraps
/var/lib/zabbix/snmptraps The volume contains the snmptraps.log log file named with received SNMP traps
/var/lib/zabbix/mibs The volume allows to add new MIB files. It does not support subdirectories, all MIBs must be placed in /var/lib/zabbix/mibs

For additional information use Zabbix official repositories in 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

When stopping or removing containers, always specify the same database type that was deployed (e.g., make down DB=pgsql).

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

Initial configuration

After downloading the images, start the containers by executing docker run command followed by additional arguments to specify required environment variables and/or mount points. Some configuration examples are provided below.

Zabbix must not be run as PID1/as an init process in containers.

Usage examples

Example 1

The example demonstrates how to run Zabbix server with MySQL database support, Zabbix web interface based on the Nginx web server and Zabbix Java gateway.

1. Create network dedicated for Zabbix component containers:

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

2. Start empty MySQL server instance

# 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 \
      -d mysql:8.0 \
      --restart unless-stopped \
      --character-set-server=utf8 --collation-server=utf8_bin \
      --default-authentication-plugin=mysql_native_password

3. Start Zabbix Java gateway instance

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

4. Start Zabbix server instance and link the instance with created MySQL server instance

# 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-5.4-latest

Zabbix server instance exposes 10051/TCP port (Zabbix trapper) to host machine.

5. Start Zabbix web interface and link the instance with created MySQL server and Zabbix server instances

# 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-5.4-latest

Zabbix web interface instance exposes 80/TCP port (HTTP) to host machine.

Example 2

The example demonstrates how to run Zabbix server with PostgreSQL database support, Zabbix web interface based on the Nginx web server and SNMP trap feature.

1. Create network dedicated for Zabbix component containers:

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

2. Start empty PostgreSQL server instance

# 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. Start Zabbix snmptraps instance

# 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-5.4-latest

Zabbix snmptrap instance exposes the 162/UDP port (SNMP traps) to host machine.

4. Start Zabbix server instance and link the instance with created PostgreSQL server instance

# 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-5.4-latest

Zabbix server instance exposes the 10051/TCP port (Zabbix trapper) to host machine.

5. Start Zabbix web interface and link the instance with created PostgreSQL server and Zabbix server instances

# 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-5.4-latest

Zabbix web interface instance exposes the 443/TCP port (HTTPS) to host machine.
Directory /etc/ssl/nginx must contain certificate with required name.

Example 3

The example demonstrates how to run Zabbix server with MySQL database support, Zabbix web interface based on the Nginx web server and Zabbix Java gateway using podman on Red Hat 8.

1. Create new pod with name zabbix and exposed ports (web-interface, Zabbix server trapper):

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

2. (optional) Start Zabbix agent container in zabbix pod location:

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

3. Create ./mysql/ directory on host and start Oracle MySQL server 8.0:

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

3. Start Zabbix server container:

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-50

4. Start Zabbix Java Gateway container:

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

5. Start Zabbix web-interface container:

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-50

Pod zabbix exposes 80/TCP port (HTTP) to host machine from 8080/TCP of zabbix-web-mysql container.