# Icinga2 Monitoring Stack

> Icinga2 monitoring with Icinga Web 2 and PostgreSQL.

- Category: Monitoring & Observability
- Difficulty: intermediate
- Components: icinga2, icingaweb2, postgresql
- Tags: icinga2, monitoring, alerting, infrastructure, nagios
- Source: https://docker.recipes/monitoring/icinga2-monitoring

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

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

## Use cases

- Enterprise infrastructure monitoring with hundreds of servers and network devices
- Multi-tenant service provider environments requiring isolated monitoring views
- DevOps teams needing API-driven monitoring configuration integrated with automation tools
- Organizations migrating from legacy Nagios seeking modern interface and clustering
- Hybrid cloud monitoring combining on-premises and cloud resource oversight
- Compliance-driven environments requiring detailed audit trails and reporting capabilities
- 24/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)

## docker-compose.yml

```yaml
services:
  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:
    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:
    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

volumes:
  postgres_data:
  icinga2_data:
  icingaweb2_data:

networks:
  icinga-network:
    driver: bridge
```

## .env

```bash
# Icinga2
WEB_PORT=8080
POSTGRES_USER=icinga
POSTGRES_PASSWORD=icinga
POSTGRES_DB=icinga
```

## Usage notes

- Icinga Web at http://localhost:8080
- Complete setup wizard
- Modern Nagios alternative
- Strong plugin ecosystem

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

