Icinga2 Monitoring Stack

intermediate

Icinga2 monitoring with Icinga Web 2 and PostgreSQL.

Overview

Icinga2 is a powerful open-source network monitoring system that evolved from Nagios, designed to monitor network resources, notify users of outages, and generate performance data for reporting. Unlike its predecessor, Icinga2 features a modern architecture with native clustering support, flexible configuration using its own domain-specific language, and enhanced scalability for enterprise environments. The system excels at monitoring hosts, services, and network devices while providing comprehensive alerting and notification capabilities. This monitoring stack combines Icinga2's robust monitoring engine with Icinga Web 2's modern PHP-based interface and PostgreSQL's enterprise-grade database backend. The architecture creates a complete monitoring solution where Icinga2 performs active and passive checks on monitored resources, stores results and configuration data in PostgreSQL, while Icinga Web 2 provides real-time dashboards, historical reporting, and administrative interfaces. PostgreSQL serves as the ideal backend due to its excellent handling of time-series data, complex queries for reporting, and ACID compliance for critical monitoring data integrity. This stack is particularly valuable for system administrators managing medium to large infrastructure environments who need reliable monitoring with professional reporting capabilities. The combination offers superior performance over file-based storage systems, supports multiple concurrent web users, and provides the scalability needed for monitoring hundreds or thousands of hosts and services while maintaining the flexibility to integrate with existing enterprise authentication systems and notification workflows.

Key Features

Native Icinga2 cluster support with automatic failover and load distribution
Advanced check scheduling with dependency-aware execution and flap detection
PostgreSQL IDO (Icinga Data Output) for high-performance time-series data storage
Icinga Web 2 responsive interface with customizable dashboards and multi-tenancy
Built-in Icinga2 API on port 5665 for programmatic configuration and monitoring
PostgreSQL JSONB storage for flexible custom variable handling in monitoring data
Icinga2 notification system with escalation rules and flexible contact management
Business process modeling through Icinga Web 2 modules for service dependency mapping

Common Use Cases

1Enterprise infrastructure monitoring with hundreds of servers and network devices
2Multi-tenant service provider environments requiring isolated monitoring views
3DevOps teams needing API-driven monitoring configuration integrated with automation tools
4Organizations migrating from legacy Nagios seeking modern interface and clustering
5Hybrid cloud monitoring combining on-premises and cloud resource oversight
6Compliance-driven environments requiring detailed audit trails and reporting capabilities
724/7 operations centers needing real-time dashboards and escalation management

Prerequisites

Docker and Docker Compose installed with minimum 2GB available RAM
Port 8080 available for Icinga Web 2 interface and port 5665 for Icinga2 API
Basic understanding of monitoring concepts like hosts, services, and check commands
PostgreSQL knowledge for database maintenance and performance tuning
Network access to monitored hosts and services from the Docker host
Valid SMTP server configuration for email notifications (post-setup)

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  postgres: 
3    image: postgres:16-alpine
4    container_name: icinga-postgres
5    restart: unless-stopped
6    environment: 
7      POSTGRES_USER: ${POSTGRES_USER:-icinga}
8      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-icinga}
9      POSTGRES_DB: ${POSTGRES_DB:-icinga}
10    volumes: 
11      - postgres_data:/var/lib/postgresql/data
12    networks: 
13      - icinga-network
14
15  icinga2: 
16    image: icinga/icinga2:latest
17    container_name: icinga2
18    restart: unless-stopped
19    ports: 
20      - "5665:5665"
21    environment: 
22      - ICINGA_MASTER=1
23    volumes: 
24      - icinga2_data:/data
25    depends_on: 
26      - postgres
27    networks: 
28      - icinga-network
29
30  icingaweb2: 
31    image: icinga/icingaweb2:latest
32    container_name: icingaweb2
33    restart: unless-stopped
34    ports: 
35      - "${WEB_PORT:-8080}:8080"
36    environment: 
37      - icingaweb.enabledModules=monitoring
38    volumes: 
39      - icingaweb2_data:/data
40    depends_on: 
41      - icinga2
42      - postgres
43    networks: 
44      - icinga-network
45
46volumes: 
47  postgres_data: 
48  icinga2_data: 
49  icingaweb2_data: 
50
51networks: 
52  icinga-network: 
53    driver: bridge

.env Template

.env

1# Icinga2
2WEB_PORT=8080
3POSTGRES_USER=icinga
4POSTGRES_PASSWORD=icinga
5POSTGRES_DB=icinga

Usage Notes

1Icinga Web at http://localhost:8080
2Complete setup wizard
3Modern Nagios alternative
4Strong plugin ecosystem

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

postgres

postgres:
  image: postgres:16-alpine
  container_name: icinga-postgres
  restart: unless-stopped
  environment:
    POSTGRES_USER: ${POSTGRES_USER:-icinga}
    POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-icinga}
    POSTGRES_DB: ${POSTGRES_DB:-icinga}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - icinga-network

icinga2

icinga2:
  image: icinga/icinga2:latest
  container_name: icinga2
  restart: unless-stopped
  ports:
    - "5665:5665"
  environment:
    - ICINGA_MASTER=1
  volumes:
    - icinga2_data:/data
  depends_on:
    - postgres
  networks:
    - icinga-network

icingaweb2

icingaweb2:
  image: icinga/icingaweb2:latest
  container_name: icingaweb2
  restart: unless-stopped
  ports:
    - ${WEB_PORT:-8080}:8080
  environment:
    - icingaweb.enabledModules=monitoring
  volumes:
    - icingaweb2_data:/data
  depends_on:
    - icinga2
    - postgres
  networks:
    - icinga-network

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  postgres:
5    image: postgres:16-alpine
6    container_name: icinga-postgres
7    restart: unless-stopped
8    environment:
9      POSTGRES_USER: ${POSTGRES_USER:-icinga}
10      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-icinga}
11      POSTGRES_DB: ${POSTGRES_DB:-icinga}
12    volumes:
13      - postgres_data:/var/lib/postgresql/data
14    networks:
15      - icinga-network
16
17  icinga2:
18    image: icinga/icinga2:latest
19    container_name: icinga2
20    restart: unless-stopped
21    ports:
22      - "5665:5665"
23    environment:
24      - ICINGA_MASTER=1
25    volumes:
26      - icinga2_data:/data
27    depends_on:
28      - postgres
29    networks:
30      - icinga-network
31
32  icingaweb2:
33    image: icinga/icingaweb2:latest
34    container_name: icingaweb2
35    restart: unless-stopped
36    ports:
37      - "${WEB_PORT:-8080}:8080"
38    environment:
39      - icingaweb.enabledModules=monitoring
40    volumes:
41      - icingaweb2_data:/data
42    depends_on:
43      - icinga2
44      - postgres
45    networks:
46      - icinga-network
47
48volumes:
49  postgres_data:
50  icinga2_data:
51  icingaweb2_data:
52
53networks:
54  icinga-network:
55    driver: bridge
56EOF
57
58# 2. Create the .env file
59cat > .env << 'EOF'
60# Icinga2
61WEB_PORT=8080
62POSTGRES_USER=icinga
63POSTGRES_PASSWORD=icinga
64POSTGRES_DB=icinga
65EOF
66
67# 3. Start the services
68docker compose up -d
69
70# 4. View logs
71docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/icinga2-monitoring/run | bash

Troubleshooting

Icinga2 fails to start with IDO database errors: Ensure PostgreSQL is fully initialized before Icinga2 startup using depends_on health checks
Icinga Web 2 shows database connection errors: Verify POSTGRES_USER and POSTGRES_DB environment variables match between services
Monitoring checks show 'Connection refused' errors: Configure Icinga2 command definitions and ensure target hosts allow connections from container network
Web interface displays 'Module monitoring not available': Enable the monitoring module through Icinga Web 2 configuration or environment variables
PostgreSQL connection limit exceeded errors: Increase max_connections in PostgreSQL configuration or reduce Icinga2 database connection pool size
Icinga2 API authentication failures: Generate and configure API users through Icinga2 configuration files mounted in the container

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

icinga2icingaweb2postgresql

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download