Rasptele

Rasptele is a private Telegram control plane for monitoring and managing a Raspberry Pi Docker server without exposing an inbound port.

Rasptele gives one trusted Telegram account a narrow interface to host health, Docker containers, and Pi-hole v6. It runs as three containers, keeps the Docker socket isolated in an allowlisted guard service, and delivers alerts through outbound Telegram long polling.

• Reports CPU, memory, disk, temperature, throttling, and container health with /status.
• Lists Docker containers and restarts only explicitly allowlisted names after confirmation.
• Reports Pi-hole v6 statistics and can temporarily disable or immediately restore blocking.
• Sends stateful alerts for host, container, Docker guard, watchdog, and Pi-hole failures.
• Retries unsent Telegram notifications from a durable SQLite outbox.
• Records recent incidents and actions for /audit.
• Restricts commands and confirmations to one numeric Telegram user ID in a private chat.

qBittorrent, Jellyfin, Coolify API, and OpenWrt integrations are not implemented.

You need:

• A 64-bit Raspberry Pi with Docker Engine and the Docker Compose plugin.
• A Telegram account.
• Outbound access from the Raspberry Pi to Telegram and GitHub Container Registry.

1. Open @BotFather in Telegram.
2. Send /newbot and follow the prompts.
3. Save the bot token. Treat it like a password.
4. Open your new bot and send it any message.

1. Open @userinfobot in Telegram.
2. Select Start.
3. Copy the positive number shown next to Id. This is your TELEGRAM_ALLOWED_USER_ID.

Wait for the v0.3.0 release workflow to pass, then run:

git clone --branch v0.3.0 --depth 1 https://github.com/maddhruv/rasptele.git
cd rasptele
cp .env.example .env
chmod 600 .env

Using an exact release tag keeps the Compose definition and container image on the same version.

Open .env and set these two values:

TELEGRAM_BOT_TOKEN=<TELEGRAM_BOT_TOKEN>
TELEGRAM_ALLOWED_USER_ID=<TELEGRAM_ALLOWED_USER_ID>

Leave the remaining variables at their defaults for your first deployment. You do not need to create a YAML configuration file.

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps

The stack starts rasptele, docker-guard, and rasptele-watchdog. It publishes no host ports. Send /start, then /status, to your bot in a private Telegram chat.

Pi-hole support is optional. Set both variables in .env, or in your platform's environment-variable editor:

PIHOLE_URL=http://192.168.68.110:8081
PIHOLE_PASSWORD=<PIHOLE_PASSWORD>

Use the Pi-hole base URL, including its port when needed. Do not include /admin or /api. PIHOLE_PASSWORD is your Pi-hole v6 web or application password.

Apply the change:

docker compose up -d

Send /pihole to view live statistics, disable blocking for five minutes, or restore blocking immediately.

• Deploy your first Rasptele bot — newcomer tutorial
• Deploy and update Rasptele — deployment how-to guides
• Configure Rasptele — configuration reference
• Operate and troubleshoot Rasptele — operational how-to guides
• Release Rasptele — maintainer release process

Rasptele operates close to the Docker host. The bot has no Docker socket mount; only docker-guard holds the socket, and it exposes a small allowlisted API inside the Compose network. Host filesystem mounts are read-only, but they still expose sensitive metadata to the bot container.

Keep the stack on a dedicated, trusted Raspberry Pi. Never publish its internal services. Read the security policy before deployment and use private vulnerability reporting for suspected security issues.

Read CONTRIBUTING.md before opening a pull request. Use SUPPORT.md to choose the right support channel, and follow the Code of Conduct in all project spaces.

User-visible changes are recorded in CHANGELOG.md.

Rasptele is licensed under the Apache License 2.0.