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.

What Rasptele does

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

Quick start

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. Create your Telegram bot

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.

2. Find your Telegram user ID

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

3. Download an exact release

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.

4. Add the required credentials

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.

5. Start Rasptele

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.

Add Pi-hole v6

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.

See Rasptele in Telegram

/status shows host and container health

/pihole shows Pi-hole statistics and controls

Choose a deployment method

Method	Image source	Guide
Docker Compose	Released image from canonical Compose	Deploy with Docker Compose
Coolify	Public Git repository at an exact release tag	Deploy with Coolify
Portainer	Released canonical Compose	Deploy with Portainer

Documentation

• 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

Security

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.

Contributing and support

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.

License

Rasptele is licensed under the Apache License 2.0.