UnraidMonitor

A Telegram bot for monitoring Docker containers and Unraid servers. Get real-time alerts, check container status, view logs, and control containers - all from Telegram.

Features

• Container Monitoring - Status, health checks, and crash detection
• Resource Alerts - CPU/memory usage with configurable thresholds
• Log Watching - Automatic alerts when errors appear in container logs
• AI Diagnostics - Claude-powered log analysis and troubleshooting
• Smart Ignore Patterns - AI-generated patterns to filter known errors
• Container Control - Start, stop, restart, and pull containers remotely
• Unraid Server Monitoring - CPU/memory, temperatures, UPS status, and array health
• Memory Pressure Management - Automatic container priority handling during high memory
• Mute System - Temporarily silence alerts per container, server, or array
• Natural Language Chat - Ask questions naturally instead of using commands

---

Table of Contents

• Installation
  • Unraid Community Apps
  • Docker on Unraid (Manual)
  • Docker on Other Systems
• Prerequisites
• Configuration
• Commands
• Alert Examples
• Troubleshooting

---

Installation

Unraid Community Apps (Recommended)

The easiest way to install on Unraid.

1. Install from Community Apps

   • Open the Unraid web UI
   • Go to Apps tab
   • Search for "Unraid Monitor Bot"
   • Click Install

2. Configure the template

   • TELEGRAM_BOT_TOKEN - Your bot token (how to get one)
   • TELEGRAM_ALLOWED_USERS - Your Telegram user ID (how to find it)
   • ANTHROPIC_API_KEY (optional) - Enables AI diagnostics
   • UNRAID_API_KEY (optional) - Enables server monitoring

3. Start the container

4. Message your bot on Telegram - send /help to verify it's working

5. Configure features (optional)

   • Edit /mnt/user/appdata/unraid-monitor/config/config.yaml
   • See Configuration for options
   • Restart the container to apply changes

---

Docker on Unraid (Manual)

If not using Community Apps, you can set it up manually.

Step 1: Create directories

mkdir -p /mnt/user/appdata/unraid-monitor/{config,data}

Step 2: Create the environment file

Create /mnt/user/appdata/unraid-monitor/config/.env:

# Required
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ALLOWED_USERS=123456789

# Optional - enables AI features
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Optional - enables Unraid server monitoring
UNRAID_API_KEY=your_unraid_api_key_here

Step 3: Add the container in Unraid

Go to Docker → Add Container and configure:

Field	Value
Name	unraid-monitor-bot
Repository	ghcr.io/dervish666/unraidmonitor:latest
Network Type	bridge or your preferred network

Add these paths:

Container Path	Host Path	Access
/app/config	/mnt/user/appdata/unraid-monitor/config	Read/Write
/app/data	/mnt/user/appdata/unraid-monitor/data	Read/Write
/var/run/docker.sock	/var/run/docker.sock	Read Only

Add these variables:

Name	Value
TELEGRAM_BOT_TOKEN	Your bot token
TELEGRAM_ALLOWED_USERS	Your user ID
ANTHROPIC_API_KEY	(optional) Your API key
UNRAID_API_KEY	(optional) Your API key
TZ	Your timezone (e.g., Europe/London)

Step 4: Start and verify

Start the container and check the logs for any errors. Message your bot on Telegram with /help.

---

Prerequisites

1. Create a Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot
3. Follow the prompts to name your bot
4. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

2. Get Your Telegram User ID

1. Message @userinfobot on Telegram
2. It will reply with your numeric user ID (e.g., 123456789)

This ID is used to restrict who can control your bot. You can add multiple IDs separated by commas: 123456789,987654321

3. Get an Anthropic API Key (Optional)

Required for AI-powered features:

• Log analysis and diagnostics (/diagnose)
• Smart ignore pattern generation
• Natural language chat

1. Sign up at console.anthropic.com
2. Go to API Keys and create a new key
3. Add it as ANTHROPIC_API_KEY

4. Get an Unraid API Key (Optional)

Required for Unraid server monitoring (CPU, memory, temps, array status).

1. In Unraid web UI, go to Settings → Management Access
2. Generate an API key
3. Add it as UNRAID_API_KEY

---

Configuration

Configuration is stored in config/config.yaml. A default file is created on first run.

Location:

• Unraid: /mnt/user/appdata/unraid-monitor/config/config.yaml
• Docker: ./config/config.yaml (relative to project root)

Essential Settings

# Containers to watch for log errors
log_watching:
  containers:
    - plex
    - radarr
    - sonarr
    - lidarr
  error_patterns:
    - "error"
    - "exception"
    - "fatal"
    - "failed"
    - "critical"
  ignore_patterns:
    - "DeprecationWarning"
    - "DEBUG"
  cooldown_seconds: 900  # 15 min between alerts for same container

# Containers to hide from status reports
ignored_containers:
  - some-temp-container

# Containers that cannot be controlled via Telegram (safety)
protected_containers:
  - unraid-monitor-bot
  - mariadb
  - postgresql14

Resource Monitoring

resource_monitoring:
  enabled: true
  poll_interval_seconds: 60
  sustained_threshold_seconds: 120  # Alert after 2 min exceeded

  defaults:
    cpu_percent: 80
    memory_percent: 85

  # Per-container overrides
  containers:
    plex:
      cpu_percent: 95    # Plex often uses high CPU
      memory_percent: 90
    handbrake:
      cpu_percent: 100   # Expected to max out

Memory Pressure Management

Automatically kills low-priority containers when system memory is critical.

memory_management:
  enabled: false  # Disabled by default - enable with caution
  warning_threshold: 90      # Notify at this %
  critical_threshold: 95     # Start killing at this %
  safe_threshold: 80         # Offer restart when below this
  kill_delay_seconds: 60     # Warning before killing
  stabilization_wait: 180    # Wait between kills

  # Never kill these (highest priority)
  priority_containers:
    - plex
    - mariadb

  # Kill these in order during memory pressure (lowest priority first)
  killable_containers:
    - handbrake
    - tdarr

Unraid Server Monitoring

unraid:
  enabled: true
  host: "192.168.1.100"  # Your Unraid IP
  port: 443
  use_ssl: true
  verify_ssl: false  # Set true if using valid SSL cert

  polling:
    system: 30   # CPU/memory poll interval
    array: 300   # Array status poll interval
    ups: 60      # UPS status poll interval

  thresholds:
    cpu_temp: 80         # Alert above this temp (C)
    cpu_usage: 95        # Alert above this %
    memory_usage: 90     # Alert above this %
    disk_temp: 50        # Alert above this temp (C)
    array_usage: 85      # Alert above this %
    ups_battery: 30      # Alert below this %

---

Commands

Container Commands

Command	Description
/status	Overview of all containers
/status <name>	Details for specific container
/resources	CPU/memory usage for all containers
/resources <name>	Detailed stats with thresholds
/logs <name> [n]	Last n log lines (default 20)
/diagnose <name> [n]	AI analysis of logs
/restart <name>	Restart a container
/stop <name>	Stop a container
/start <name>	Start a container
/pull <name>	Pull latest image and recreate

Tip: Partial names work - /status rad matches radarr

Unraid Server Commands

Command	Description
/server	Server overview (CPU, memory, temps)
/server detailed	Full metrics including per-core temps
/array	Array status and disk health
/disks	Detailed disk information

Alert Management

Command	Description
/mute <name> <duration>	Mute container (e.g., /mute plex 2h)
/unmute <name>	Unmute a container
/mute-server <duration>	Mute server alerts
/unmute-server	Unmute server alerts
/mute-array <duration>	Mute array alerts
/unmute-array	Unmute array alerts
/mutes	Show all active mutes
/ignore	Show recent errors to create ignore patterns
/ignores	List all ignore patterns
/cancel-kill	Cancel pending memory pressure kill

Duration formats: 30m, 2h, 1d, 1w

Quick Access

Command	Description
/manage	Dashboard with quick action buttons
/help	Show help message

Natural Language Chat

Instead of commands, you can ask questions naturally:

• "What's wrong with plex?"
• "Why is my server slow?"
• "Is anything crashing?"
• "Show me radarr logs"
• "Restart sonarr" (asks for confirmation)

Follow-up questions work too - say "restart it" after discussing a container.

Note: Requires ANTHROPIC_API_KEY to be configured.

---

Alert Examples

All alerts include quick action buttons.

Crash Alert

🔴 CONTAINER CRASHED: radarr

Exit code: 137 (OOM killed)
Image: linuxserver/radarr:latest
Uptime: 2h 34m

[🔄 Restart] [📋 Logs] [🔍 Diagnose]
[🔕 Mute 1h] [🔕 Mute 24h]

Resource Alert

⚠️ HIGH MEMORY USAGE: plex

Memory: 92% (threshold: 85%)
        7.4GB / 8.0GB limit
Exceeded for: 3 minutes

CPU: 45% (normal)

[📋 Logs] [🔍 Diagnose]
[🔕 Mute 1h] [🔕 Mute 24h]

Log Error Alert

⚠️ ERRORS IN: sonarr

Found 3 errors in the last 15 minutes

Latest: Database connection failed: timeout

[🔇 Ignore Similar] [🔕 Mute 1h]
[📋 Logs] [🔍 Diagnose]

---

Troubleshooting

Bot not responding

1. Check the container is running: docker ps | grep unraid-monitor
2. Check logs for errors: docker logs unraid-monitor-bot
3. Verify TELEGRAM_BOT_TOKEN is correct
4. Verify your user ID is in TELEGRAM_ALLOWED_USERS

"Permission denied" errors

This means the container can't access the Docker socket.

1. Check your Docker socket GID:

   ls -ln /var/run/docker.sock

   Look at the 4th column (e.g., 281 on Unraid, 999 on Ubuntu)

2. If using docker-compose, set DOCKER_GID in .env:

   echo "DOCKER_GID=999" > .env

3. Rebuild the container:

   docker-compose build --no-cache
   docker-compose up -d

4. Last resort: Edit docker-compose.yml and uncomment user: root

AI features not working

• Verify ANTHROPIC_API_KEY is set correctly
• Check logs for API errors
• The bot works without AI - you'll get basic alerts, but /diagnose and natural language chat won't work

Unraid monitoring not working

• Verify UNRAID_API_KEY is set
• Check the unraid section in config.yaml has correct host and port
• If using self-signed certs, set verify_ssl: false

Container not starting

Check logs immediately after start:

docker logs unraid-monitor-bot

Common issues:

• Missing TELEGRAM_BOT_TOKEN or TELEGRAM_ALLOWED_USERS
• Invalid configuration in config.yaml
• Docker socket permission issues (see above)

Changes to config.yaml not applying

Restart the container after editing config:

docker restart unraid-monitor-bot

---

Data Storage

All persistent data is stored in mounted volumes:

config/
├── config.yaml           # Main configuration
└── .env                  # Environment variables (secrets)

data/
├── ignored_errors.json   # Ignore patterns
├── mutes.json            # Container mutes
├── server_mutes.json     # Server mutes
└── array_mutes.json      # Array mutes

---

Requirements

• Docker
• Telegram Bot Token
• (Optional) Anthropic API key for AI features
• (Optional) Unraid API key for server monitoring

---

License

MIT