Beszel Telegram ChatOps

A Telegram-based ChatOps companion for Beszel Server Monitoring Hub.

This service extends an existing Beszel Hub deployment with interactive Telegram commands. Users can link their Telegram account, view server availability, request real-time metrics, and capture dashboard screenshots without modifying the main Beszel application.

Overview

This project runs as a separate Node.js microservice instead of being embedded into the Beszel Hub binary. That separation keeps the core Beszel installation lightweight, easier to upgrade, and isolated from browser automation dependencies such as Playwright.

Features

• Automatic schema provisioning for Telegram-related fields in the Beszel PocketBase database
• /start to introduce the bot and explain the account-linking flow
• /bind <token> to link a Telegram account using a bind token
• /unlink to disconnect a previously linked Telegram account
• /list to display accessible systems with inline action buttons
• /status <node> to retrieve real-time CPU, memory, disk, and network usage
• /capture <node> to generate a dashboard screenshot from Beszel Hub using Playwright
• Integrated Task Queue to handle concurrent screenshot requests smoothly, especially on servers with limited resources (e.g., 1GB RAM)
• Support for reusing the same Telegram bot token already used by Shoutrrr notifications

Prerequisites

• Node.js 18 or later
• A running Beszel Hub instance
• A Telegram bot token from @BotFather

Installation

Clone the repository and install dependencies:

git clone https://github.com/your-org/beszel-telegram-chatops.git
cd beszel-telegram-chatops
npm install

Install the Chromium browser required by Playwright:

npx playwright install chromium

Configuration

Create a local environment file:

cp .env.example .env

Update .env with your deployment values:

• TELEGRAM_BOT_TOKEN: Telegram bot token obtained from @BotFather
• BESZEL_URL: Base URL of your Beszel Hub instance, for example http://127.0.0.1:8090
• ADMIN_EMAIL: Administrator or superuser email for Beszel Hub
• ADMIN_PASSWORD: Administrator or superuser password for Beszel Hub

These credentials are used for schema provisioning and API access to system data.

Running the Service

Start the bot with Node.js:

node index.js

For production deployments, run the process under a supervisor such as PM2:

pm2 start index.js --name beszel-telegram-chatops

Command Reference

• /start: Shows onboarding instructions for new users
• /bind <token>: Links the current Telegram account to a Beszel user
• /unlink: Removes the Telegram link from the current user
• /list: Displays systems available to the authenticated user
• /status <node>: Returns current metrics for a specific node
• /capture <node>: Sends a screenshot of the selected node dashboard

Architecture

The codebase is intentionally small and split by responsibility:

• index.js: Telegram bot entry point and command handlers
• src/api.js: Beszel and PocketBase API communication helpers
• src/auth.js: Telegram account binding and unlinking logic
• src/schema.js: Startup-time schema provisioning for Telegram integration fields
• src/capture.js: Playwright-based screenshot generation and cropping logic
• src/queue.js: Simple task queue with concurrency limit to ensure system stability

Notes

• The service assumes administrator access to the Beszel Hub instance for initialization tasks.
• Screenshot capture depends on Playwright and a working Chromium installation.
• Users must link their Telegram account before they can access protected commands.

License

This project currently uses the license defined in package.json.