Pi Assistant Loruv V5
Telegram Tabanlı Raspberry Pi, Docker ve Ev Sunucusu Yönetim Asistanı
Pi Assistant Loruv, Raspberry Pi tabanlı ev sunucumu yalnızca izlemek değil; Docker altyapısını, sistem kaynaklarını, ağ durumunu, depolama birimlerini, servisleri ve dosya işlemlerini Telegram üzerinden merkezi biçimde yönetebilmek amacıyla geliştirdiğim açık kaynaklı bir Python projesidir.
Projenin ilk sürümleri CPU, RAM, disk kullanımı, sıcaklık, IP adresleri ve temel Docker container işlemleri üzerine kuruluydu. Zaman içinde ihtiyaçlar arttıkça proje de gelişti ve V5 sürümüyle birlikte basit bir izleme botundan, günlük sunucu yönetiminde kullanılabilecek kapsamlı bir Telegram tabanlı yönetim katmanına dönüştü.
Bugün Pi Assistant Loruv; Raspberry Pi sistem sağlığını izleyebilir, gerçek host süreçlerini görüntüleyebilir, Docker container’larını yönetebilir, container güncellemelerini kontrol edebilir, açık portları analiz edebilir, SSD/SMART verilerini okuyabilir, systemd servislerini izleyebilir, dosya indirebilir ve yönetebilir, ağ testleri gerçekleştirebilir ve kritik durumlarda otomatik Telegram bildirimleri gönderebilir.
Projenin Amacı
Raspberry Pi ve self-hosted ev sunucuları genellikle 7/24 çalışır. Ancak bu sistemlerde aynı anda birçok bileşenin takip edilmesi gerekir:
- CPU ve RAM kullanımı
- İşlemci sıcaklığı
- SSD doluluk oranı ve sağlık durumu
- İnternet bağlantısı
- Genel IP değişiklikleri
- Docker container durumları
- Container güncellemeleri
- Açık portlar
- Sistem servisleri
- Disk yazma miktarı
- Undervoltage ve throttling durumları
- Failed systemd servisleri
- İndirilen ve yüklenen dosyalar
Bu bilgileri farklı panellerden veya sürekli SSH bağlantısıyla takip etmek yerine tek bir Telegram botu üzerinden erişilebilir hâle getirmek istedim.
Pi Assistant Loruv’un temel yaklaşımı şu oldu:
Sunucunun durumunu öğrenmek için sunucuya gitmek yerine, sunucunun önemli bilgileri gerektiğinde bana getirmesi.
V5 FINAL ile Gelen Yapı
V5 sürümü, projenin şimdiye kadarki en kapsamlı sürümüdür.
Etkileşimli Telegram Yönetim Paneli
Artık komutları ezberlemek zorunda kalmadan bot içerisindeki butonlarla ilerlemek mümkün.
Ana yönetim menüsü üzerinden şu bölümlere erişilebilir:
- Sistem
- Docker
- Süreçler
- Portlar
- Ağ
- Depolama
- Dosyalar
- URL ile indirme
- systemd servisleri
- SSD / SMART
- Host araçları
- Sistem sağlığı
- Raporlar
- Olay geçmişi
- Uyarılar
- Host yönetimi
Bu yapı sayesinde Telegram, Raspberry Pi için küçük bir mobil yönetim paneli gibi kullanılabilir.
Gelişmiş Sistem İzleme
Pi Assistant Loruv Raspberry Pi’den aşağıdaki sistem bilgilerini okuyabilir:
- Raspberry Pi modeli
- Hostname
- İşletim sistemi
- Kernel bilgisi
- CPU kullanım oranı
- Fiziksel ve mantıksal CPU sayısı
- CPU frekansı
- Load average
- İşlemci sıcaklığı
- RAM kullanımı
- Swap kullanımı
- Disk doluluk oranı
- Disk okuma/yazma miktarı
- Sistem çalışma süresi
- Boot zamanı
- Gönderilen ve alınan ağ verisi
- Yerel IP adresi
- Genel IP adresi
Sistem ekranı yalnızca anlık değerleri göstermekle kalmaz; kritik değerler izleme sistemi tarafından arka planda takip edilir.
Gerçek Raspberry Pi Süreçlerini Görüntüleme
Docker içerisinde çalışan bir uygulamanın varsayılan olarak yalnızca kendi process namespace’ini görmesi önemli bir teknik problemdi.
V5’te bu sorun host /proc dizininin container içine salt okunur bağlanması ve psutil.PROCFS_PATH değerinin host process filesystem’ine yönlendirilmesiyle çözüldü.
Bu sayede Pi Assistant artık yalnızca kendi Python process’ini değil, Raspberry Pi üzerinde çalışan gerçek süreçleri görüntüleyebilir.
Örneğin:
- systemd
- dockerd
- containerd
- tailscaled
- smbd
- Python uygulamaları
- Docker container process’leri
- diğer Linux servisleri
Süreçler;
- CPU kullanımına
- RAM kullanımına
- disk I/O miktarına
göre sıralanabilir.
Bir PID seçildiğinde aşağıdaki ayrıntılar görüntülenebilir:
- PID / PPID
- process adı
- kullanıcı
- durum
- CPU kullanımı
- RAM kullanımı
- RSS / VMS
- thread sayısı
- CPU core
- disk read/write
- açık dosyalar
- ağ bağlantıları
- çalışma süresi
- executable
- current working directory
- command line
Docker Yönetimi
Docker yönetimi Pi Assistant Loruv’un merkezinde yer almaktadır.
Container Yönetimi
Telegram üzerinden:
- tüm container’ları listeleme
- running / stopped / paused durumlarını görüntüleme
- container başlatma
- container durdurma
- container yeniden başlatma
- pause / unpause
- image bilgisini görüntüleme
- restart sayısını görüntüleme
- health durumunu kontrol etme
- container IP adreslerini görüntüleme
- yayınlanan portları görüntüleme
- mount bilgilerini görüntüleme
- resource limitlerini görüntüleme
işlemleri gerçekleştirilebilir.
Container Kaynak Kullanımı
Her container için:
- CPU
- RAM
- network RX
- network TX
- block read
- block write
istatistikleri görüntülenebilir.
Ayrıca merkezi Docker kaynak ekranı sayesinde bütün çalışan container’lar aynı anda karşılaştırılabilir.
Bu özellik özellikle Raspberry Pi gibi kaynakların sınırlı olduğu sistemlerde hangi servisin daha fazla CPU, RAM veya SSD yazımı oluşturduğunu hızlı biçimde tespit etmeyi kolaylaştırır.
Tek Tuşla Tüm Docker Güncellemelerini Kontrol Etme
V5 ile birlikte en önemli geliştirmelerden biri merkezi Docker image güncelleme kontrolüdür.
Tek bir Telegram butonuyla bütün uygun container’lar kontrol edilebilir.
Sonuçlar şu şekilde sınıflandırılır:
- Güncel
- Güncelleme mevcut
- Kontrol edilemedi
- Yoksayıldı
Pi Assistant kendi container’ını varsayılan olarak toplu güncelleme listesinden hariç tutar.
Güncelleme kontrolü container’ı değiştirmez. Güncelleme bulunan container’lar için deploy işlemi ayrıca onaylanır.
Güvenli Container Recreate ve Rollback
Container güncellenirken çalışan yapılandırma mümkün olduğunca korunur.
Yeni image çekildikten sonra container recreate edilir ve yeni container’ın çalışması kontrol edilir.
Güncelleme sonrası container başlatılamaz veya health kontrolünden geçemezse sistem eski yapıya geri dönmek için rollback işlemi uygulamayı dener.
Statik IP, riskli network yapılandırmaları veya güvenli biçimde yeniden oluşturulamayacak yapılandırmalar tespit edildiğinde otomatik recreate reddedilir.
Bu yaklaşım, otomasyonu mümkün olduğunca güvenli tutmak için tercih edildi.
Docker Port Merkezi
V5 bütün Docker container portlarını tek ekranda gösterebilir.
Örneğin:
uptime-kuma
0.0.0.0:3002 → 3001/tcp
portainer
0.0.0.0:9443 → 9443/tcp
Port ekranında:
- Host IP
- Host port
- Container port
- TCP / UDP
- dışarı açık binding
- yalnız localhost üzerinde çalışan servisler
- Docker tarafından expose edilen ancak publish edilmeyen portlar
görüntülenebilir.
Ayrıca Docker dışındaki gerçek host listening portları da incelenebilir.
Böylece belirli bir portun hangi process veya container tarafından kullanıldığı daha kolay tespit edilebilir.
Docker Disk ve Temizlik Yönetimi
Docker zaman içerisinde image, build cache, stopped container ve kullanılmayan kaynaklarla ciddi miktarda disk alanı tüketebilir.
Pi Assistant üzerinden:
- Docker disk kullanımını görüntüleme
- image kullanımını inceleme
- container writable layer kullanımını görüntüleme
- volume bilgilerini görüntüleme
- build cache miktarını görüntüleme
- dangling image temizleme
- kullanılmayan image temizleme
- stopped container temizleme
- build cache temizleme
- kullanılmayan network temizleme
- kullanılmayan volume temizleme
işlemleri yapılabilir.
Veri kaybı oluşturabilecek işlemler doğrudan uygulanmaz ve Telegram üzerinden ikinci onay gerektirir.
SSD ve SMART Sağlık İzleme
Raspberry Pi sistemimde USB SSD kullandığım için projenin V5 sürümünde depolama sağlığına özel önem verdim.
SMART desteği bulunan disklerde aşağıdaki bilgiler görüntülenebilir:
- Disk modeli
- Seri numarası
- Firmware sürümü
- Kapasite
- SMART genel sağlık durumu
- Disk sıcaklığı
- Power-on hours
- Power cycle count
- Unsafe shutdown sayısı
- Reallocated sector
- Pending sector
- Offline uncorrectable sector
- CRC error
- NVMe percentage used
- Available spare
- Media/Data Integrity Errors
- NVMe toplam okuma/yazma miktarı
SMART short ve long self-test işlemleri başlatılabilir.
Tam smartctl -x çıktısı Telegram üzerinden .txt dosyası olarak alınabilir.
SMART otomatik taraması varsayılan olarak kapalıdır. Bunun nedeni bazı USB-SATA bridge ve disklerde gereksiz SMART sorgularının disk uyku davranışını etkileyebilmesidir.
Raspberry Pi Güç ve Throttling Takibi
Raspberry Pi’ye özel olarak vcgencmd get_throttled üzerinden güç ve thermal durumları da takip edilebilir.
İzlenen durumlar:
- anlık undervoltage
- geçmiş undervoltage
- anlık throttling
- geçmiş throttling
- frequency cap
- geçmiş frequency cap
- soft temperature limit
- ARM clock
- core voltage
Kısa süreli bir undervoltage olayı kontrol anında aktif olmasa bile firmware’in geçmiş durum bitlerinden tespit edilebilir.
Ağ ve İnternet Araçları
Pi Assistant ağ katmanında aşağıdaki bilgileri görüntüleyebilir:
- Yerel IP
- Genel IP
- IPv4
- IPv6
- network interface’leri
- interface link durumu
- MTU
- link speed
- RX / TX
- paket miktarları
- network error/drop değerleri
Ayrıca:
- internet erişim testi
- gateway ping
- Cloudflare DNS ping
- Google DNS ping
- DNS çözümleme kontrolü
- packet loss
- speedtest
- dış IP değişimi
gibi kontroller gerçekleştirilebilir.
İnternet bağlantısı kesildiğinde veya tekrar geldiğinde Telegram bildirimi gönderilir.
systemd Servis Yönetimi
V5 host üzerinde çalışan systemd servislerini de izleyebilir.
Telegram üzerinden:
- servisleri listeleme
- failed servisleri görüntüleme
- servis detaylarını inceleme
- Main PID
- active/sub state
- memory
- CPU time
- restart count
- unit file state
- journal loglarını görüntüleme
- journal çıktısını
.txtdosyası olarak alma
işlemleri gerçekleştirilebilir.
Servis restart yetkisi bütün systemd servislerine verilmez.
Yalnızca ayrı bir allowlist içerisinde tanımlanan servisler Telegram üzerinden restart edilebilir.
URL ile Sunucuya Dosya İndirme
V5 ile Telegram botuna bir HTTP/HTTPS bağlantısı göndererek Raspberry Pi üzerindeki SSD’ye dosya indirilebilir.
İndirme öncesinde:
- dosya adı
- yaklaşık boyut
- Content-Type
- hedef dizin
- boş disk alanı
kontrol edilir.
İndirme sırasında:
- ilerleme yüzdesi
- indirilen veri miktarı
- hız
- ETA
görüntülenebilir.
İndirme tamamlandıktan sonra SHA-256 özeti hesaplanabilir.
Varsayılan download dizini:
/srv/downloads
URL Downloader Güvenliği
Sunucu taraflı bir URL downloader geliştirilirken SSRF riski özellikle dikkate alındı.
Bu nedenle downloader:
- yalnız HTTP / HTTPS kabul eder
- localhost adreslerini reddeder
- private LAN IP’lerini reddeder
- link-local adresleri reddeder
- Docker internal network hedeflerini reddeder
- metadata servis adreslerini reddeder
- izin verilmeyen portları reddeder
- redirect hedeflerini tekrar kontrol eder
- maksimum dosya boyutu uygular
- minimum boş SSD alanını korur
Varsayılan olarak yalnızca 80 ve 443 portları izinlidir.
Telegram Dosya Yöneticisi
Pi Assistant iki kontrollü dosya alanını yönetebilir:
/srv/downloads
/srv/uploads
Telegram üzerinden:
- dosyaları listeleme
- dosya boyutunu görüntüleme
- değiştirilme zamanını görüntüleme
- SHA-256 hesaplama
- dosyayı Telegram’a gönderme
- dosya silme
- download/upload alanını temizleme
işlemleri yapılabilir.
Silme işlemleri ikinci onay gerektirir.
Kritik Linux dizinleri dosya yöneticisinin yazma alanına dahil edilmez.
Telegram’dan Raspberry Pi’ye Dosya Yükleme
Telegram’a gönderilen belgeler kontrollü biçimde Raspberry Pi’ye kaydedilebilir.
Varsayılan hedef:
/srv/uploads
Bu özellik küçük yapılandırma dosyaları, loglar, arşivler veya diğer çalışma dosyalarını telefondan sunucuya taşımayı kolaylaştırır.
Büyük Dosya Analizi
SSD alanının neden dolduğunu tespit etmek için host üzerinde belirli güvenli alanlarda büyük dosya taraması yapılabilir.
Örneğin en büyük dosyalar listelenerek gereksiz disk kullanımının kaynağı hızlı biçimde tespit edilebilir.
Otomatik Uyarılar
Pi Assistant aşağıdaki durumlarda Telegram üzerinden otomatik bildirim gönderebilir:
- CPU kullanımı yüksek
- RAM kullanımı yüksek
- Swap kullanımı yüksek
- Disk doluluk oranı yüksek
- CPU sıcaklığı yüksek
- Load yüksek
- İnternet bağlantısı kesildi
- İnternet bağlantısı geri geldi
- Genel IP değişti
- Container durumu değişti
- Container health durumu değişti
- Container restart sayısı arttı
- Raspberry Pi undervoltage
- Raspberry Pi throttling
- Frequency cap
- systemd servisi failed
- failed servis yeniden normale döndü
- SMART sağlık problemi
Değer normale döndüğünde de recovery bildirimi gönderilebilir.
Sistem Sağlığı
V5’in sağlık ekranı farklı alt sistemleri tek yerde değerlendirir.
Kontrol edilen alanlardan bazıları:
- CPU
- RAM
- Swap
- Disk
- Load
- Sıcaklık
- İnternet
- Docker daemon
- SMART
- Raspberry Pi power state
- failed systemd servisleri
Bu sayede ayrıntılara girmeden önce sistemin genel durumu hızlı biçimde görülebilir.
Olay Geçmişi
Pi Assistant sürekli telemetry verisi yazarak SSD üzerinde gereksiz I/O oluşturmak yerine yalnız önemli olayları saklar.
Örneğin:
- internet kesintisi
- genel IP değişimi
- container stop/start
- Docker health problemi
- SMART uyarısı
- undervoltage
- yüksek sıcaklık
- dosya indirme
- dosya silme
gibi olaylar sınırlı bir geçmiş içerisinde tutulabilir.
Varsayılan olarak yalnızca son belirli sayıdaki olay korunur.
SSD Dostu Tasarım
Raspberry Pi sistemimde SSD üzerinde çalışan birçok Docker servisi bulunduğu için Pi Assistant Loruv’un kendisinin gereksiz disk yazımı oluşturmasını istemedim.
Bu nedenle V5’te bazı özel kararlar alındı:
- Container root filesystem
read_only - geçici dosyalar
tmpfsüzerinde - Python log seviyesi varsayılan olarak
WARNING - sürekli metric database yok
- önemli olaylar sınırlı sayıda tutuluyor
- disk-write trend örnekleri RAM’de işleniyor
- Docker logging için
localdriver kullanılıyor - log rotation uygulanıyor
- SMART otomatik sorgulama varsayılan olarak kapalı
Örnek Docker log yapılandırması:
logging:
driver: local
options:
max-size: "2m"
max-file: "2"
Amaç, sistem izleme aracının kendisinin SSD üzerinde gereksiz yük oluşturmamasıdır.
Güvenlik Yaklaşımı
Pi Assistant oldukça güçlü işlemler gerçekleştirebildiği için güvenlik projenin temel parçalarından biridir.
Telegram Kullanıcı Yetkilendirmesi
Bot yalnızca yapılandırılmış ALLOWED_USER_ID değerine sahip Telegram kullanıcısından gelen işlemleri kabul eder.
Docker Socket
Docker yönetimi için Docker socket kullanılır:
/var/run/docker.sock
Docker socket root seviyesine yakın yetki sağladığı için botun erişimi yalnız güvenilir Telegram hesabıyla sınırlandırılmıştır.
Rastgele Shell Erişimi Yok
Telegram üzerinden serbest biçimde shell komutu çalıştırma özelliği özellikle eklenmemiştir.
Host üzerinde yapılabilecek kritik işlemler önceden tanımlanmış allowlist komutlarıyla sınırlandırılır.
Forced-Command SSH Gateway
SMART, systemd, vcgencmd, speedtest, reboot ve shutdown gibi host seviyesinde yetki isteyen özellikler için ayrı bir SSH forced-command gateway kullanılabilir.
Akış:
Telegram
│
▼
Pi Assistant Container
│
▼
SSH Restricted User
│
▼
Forced Command Gateway
│
▼
Allowlist
│
▼
Host Helper
Böylece Telegram üzerinden keyfi root shell erişimi verilmez.
Kritik İşlem Onayı
Aşağıdaki gibi kritik işlemler ikinci onay gerektirir:
- container stop
- container restart
- container recreate
- toplu Docker update
- Docker cleanup
- volume prune
- systemd restart
- SMART self-test
- Raspberry Pi reboot
- Raspberry Pi shutdown
- dosya silme
Onay butonları süreli ve tek kullanımlıktır.
Host Yönetimi
Güvenli host helper yapılandırıldıktan sonra Telegram üzerinden:
- Raspberry Pi yeniden başlatma
- Raspberry Pi kapatma
- Docker daemon yeniden başlatma
işlemleri gerçekleştirilebilir.
Bu işlemler her zaman kullanıcı onayı ister.
Kullanılan Teknolojiler
Projede kullandığım başlıca teknolojiler:
- Python
- Docker
- Docker Compose
- Docker Engine API
- Docker SDK for Python
- Raspberry Pi OS
- Linux
/proc - Linux
/sys - psutil
- Telegram Bot API
- python-telegram-bot
- Portainer
- systemd
- journalctl
- smartmontools
- vcgencmd
- SSH
- Speedtest CLI
- Git
- GitHub
Sistem Mimarisi
Telegram
│
▼
Telegram Bot API
│
▼
Pi Assistant Loruv V5
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
System Monitor Docker Engine File Manager
│ │ │
│ │ ├── Downloads
│ │ └── Uploads
│ │
│ ├── Containers
│ ├── Images
│ ├── Networks
│ ├── Volumes
│ ├── Updates
│ └── Cleanup
│
├── /host/proc
├── /host/sys
├── Network
├── Disk I/O
└── Health
│
▼
Restricted SSH Gateway
│
┌───────────────┼───────────────┐
▼ ▼ ▼
SMART systemd vcgencmd
│ │ │
└───────────────┼───────────────┘
▼
Raspberry Pi Host
Docker ve Portainer
Projeyi hem terminal üzerinden Docker Compose ile hem de Portainer Repository yöntemiyle çalıştırmak mümkündür.
Ben repository tabanlı kullanımda Portainer’ın GitHub repository’sini doğrudan çekmesini tercih ediyorum.
Repository:
github.com/emrecagri/Pi-Assistant-Loruv
Portainer Repository yapılandırması:
Repository URL:
https://github.com/emrecagri/Pi-Assistant-Loruv
Repository reference:
refs/heads/main
Compose path:
compose.yml
Bot tokeni ve Telegram kullanıcı ID’si GitHub kaynak koduna yazılmaz.
Portainer Environment Variables bölümünde:
BOT_TOKEN
ALLOWED_USER_ID
olarak tanımlanabilir.
Diğer ayarlar Docker Compose içerisindeki varsayılan değerlerle çalışabilir.
GitHub ve Açık Kaynak
Pi Assistant Loruv açık kaynak olarak geliştirilmektedir.
Kaynak kodu, Docker yapılandırması, host helper bileşenleri ve ayrıntılı Türkçe/İngilizce kurulum dokümantasyonu GitHub repository’sinde bulunmaktadır.
GitHub:
Projede Öğrendiğim ve Uyguladığım Konular
Pi Assistant Loruv benim için yalnızca bir Telegram botu geliştirme çalışması olmadı.
Proje sırasında özellikle şu alanlarda pratik yaptım:
- Docker Engine API kullanımı
- Docker SDK ile container yönetimi
- Linux host bilgilerini container içerisinden güvenli biçimde okuma
/procve/sysfilesystem yapıları- process monitoring
- async Python
- Telegram inline keyboard tasarımı
- callback tabanlı kullanıcı arayüzü
- event monitoring
- threshold alert sistemleri
- network diagnostics
- SMART disk monitoring
- systemd yönetimi
- SSH forced-command güvenliği
- SSRF güvenliği
- dosya transferi
- Docker image update süreçleri
- rollback stratejileri
- disk I/O optimizasyonu
- SSD-dostu logging
- Portainer GitOps / Repository deployment
- self-hosted sistem güvenliği
Projenin gelişimi sırasında her yeni özellik gerçek kullanımda karşılaştığım bir ihtiyaca göre eklendi.
V5 FINAL Sonuç
Pi Assistant Loruv’un ilk amacı Raspberry Pi’nin sıcaklığını, RAM kullanımını ve Docker container durumlarını Telegram’dan kontrol edebilmekti.
V5 FINAL sürümüyle proje bu sınırın oldukça ötesine geçti.
Bugün Pi Assistant Loruv;
- sistem izleme,
- gerçek host process analizi,
- Docker yönetimi,
- Docker güncelleme kontrolü,
- port analizi,
- SSD/SMART sağlık takibi,
- network diagnostics,
- systemd izleme,
- dosya transferi,
- URL downloader,
- otomatik uyarılar,
- host yönetimi,
- güvenli kritik işlem akışları
gibi farklı yönetim katmanlarını tek bir Telegram arayüzünde birleştiren kapsamlı bir self-hosted yardımcı uygulama hâline geldi.
En önemli tasarım hedeflerinden biri ise projenin Raspberry Pi üzerinde düşük kaynak kullanımıyla ve mümkün olduğunca az SSD yazımı oluşturarak çalışmaya devam etmesidir.
English Version
Pi Assistant Loruv V5 FINAL
Telegram-Based Raspberry Pi, Docker and Home Server Management Assistant
Pi Assistant Loruv is an open-source Python project I developed to monitor and manage my Raspberry Pi-based home server infrastructure through Telegram.
The first versions of the project focused on CPU, RAM, disk usage, CPU temperature, IP addresses and basic Docker container operations. As my self-hosted environment grew, the project evolved into a much more comprehensive management layer.
With V5 FINAL, Pi Assistant Loruv is no longer only a monitoring bot. It acts as a lightweight Telegram-based control center for Raspberry Pi, Docker, networking, storage, Linux services and file operations.
Project Goal
Raspberry Pi home servers often run continuously and host many independent services.
Monitoring all of the following manually is not practical:
- CPU and memory usage
- processor temperature
- SSD usage and health
- internet connectivity
- public IP changes
- Docker container status
- image updates
- listening ports
- Linux services
- disk write activity
- undervoltage and throttling
- failed systemd services
- downloaded and uploaded files
Instead of checking several dashboards or connecting over SSH for every small task, I wanted one lightweight interface that I already use every day: Telegram.
The core idea became:
Instead of going to the server to check its state, the server should provide the information when I need it.
Interactive Telegram Management
V5 provides an inline-button based interface for:
- System
- Docker
- Processes
- Ports
- Network
- Storage
- Files
- URL Downloader
- systemd Services
- SSD / SMART
- Host Tools
- Health
- Reports
- Event History
- Alerts
- Host Management
This effectively turns Telegram into a compact mobile administration interface for the Raspberry Pi.
System Monitoring
Pi Assistant can report:
- Raspberry Pi model
- hostname
- operating system
- kernel
- CPU usage
- physical/logical CPU count
- CPU frequency
- load average
- CPU temperature
- RAM
- swap
- disk usage
- disk I/O
- uptime
- boot time
- network traffic
- local IP
- public IP
Background monitors can generate alerts when configured thresholds are exceeded.
Real Host Process Monitoring
A major technical improvement in V5 was solving process visibility from inside Docker.
The host /proc filesystem is mounted read-only and psutil.PROCFS_PATH is redirected to the host process filesystem.
As a result, Pi Assistant can inspect real Raspberry Pi processes instead of seeing only its own container namespace.
Processes can be sorted by:
- CPU
- RAM
- disk I/O
Detailed process information includes:
- PID / PPID
- user
- status
- CPU
- memory
- RSS / VMS
- threads
- CPU core
- disk read/write
- open files
- network connections
- runtime
- executable
- CWD
- command line
Docker Management
Telegram can be used to:
- list containers
- inspect status and health
- start containers
- stop containers
- restart containers
- pause / unpause
- inspect images
- view restart counts
- inspect network addresses
- inspect exposed and published ports
- inspect mounts
- inspect resource limits
Per-container statistics include:
- CPU
- RAM
- network RX/TX
- block read/write
A centralized resource screen makes it easy to identify the containers consuming the most CPU, memory, network bandwidth or SSD write activity.
One-Tap Docker Update Scan
V5 can check all eligible Docker containers for image updates from a single Telegram action.
Containers are classified as:
- Up to date
- Update available
- Check failed
- Ignored
The update scan itself does not modify running containers.
Deploying available updates is a separate, confirmed action.
Pi Assistant excludes its own container from bulk updates by default.
Safe Recreate and Rollback
When updating a container, Pi Assistant attempts to preserve the current configuration.
After pulling the new image, the container is recreated and checked.
If the new container fails to start or becomes unhealthy, Pi Assistant attempts to restore the previous container configuration.
Unsafe automatic recreate scenarios such as certain static-IP or complex network configurations are rejected instead of being modified blindly.
Docker Port Center
All Docker port mappings can be viewed in one place.
The port center displays:
- Host IP
- Host port
- Container port
- TCP / UDP
- public bindings
- localhost-only bindings
- exposed but unpublished ports
Real host listening ports can also be inspected, making it easier to determine which process or container owns a specific port.
Docker Disk and Cleanup
Pi Assistant provides visibility into Docker disk consumption:
- images
- writable container layers
- volumes
- build cache
Cleanup actions are available for:
- dangling images
- unused images
- stopped containers
- build cache
- unused networks
- unused volumes
Potentially destructive cleanup operations require confirmation.
SSD / SMART Monitoring
Storage health is especially important on an always-on Raspberry Pi.
When SMART is supported, Pi Assistant can report:
- model
- serial number
- firmware
- capacity
- overall SMART health
- temperature
- power-on hours
- power cycles
- unsafe shutdowns
- reallocated sectors
- pending sectors
- offline uncorrectable sectors
- CRC errors
- NVMe percentage used
- available spare
- media/data integrity errors
- NVMe read/write totals
SMART short and long tests can be triggered.
Full smartctl -x output can be delivered as a .txt file through Telegram.
Raspberry Pi Power Monitoring
Using Raspberry Pi firmware information, V5 can monitor:
- current undervoltage
- historical undervoltage
- current throttling
- historical throttling
- frequency capping
- historical frequency capping
- soft temperature limits
- ARM clock
- core voltage
Historical firmware flags make it possible to detect short events that may no longer be active at the exact time of the next check.
Network Diagnostics
Network tools include:
- local IP
- public IP
- IPv4 / IPv6
- network interfaces
- MTU
- link speed
- RX / TX
- packet counts
- network errors and drops
- gateway ping
- Cloudflare DNS ping
- Google DNS ping
- DNS resolution testing
- packet loss
- speedtest
Internet outages, recoveries and public IP changes can generate Telegram alerts.
systemd Service Monitoring
Host systemd services can be inspected from Telegram.
Available information includes:
- active/sub state
- Main PID
- memory
- CPU time
- restart count
- unit file state
- recent journal output
Journal logs can be delivered as .txt files.
Restart operations are restricted to explicitly allowlisted services.
URL Downloader
V5 can download HTTP/HTTPS files directly to the Raspberry Pi from a URL sent through Telegram.
The downloader checks:
- filename
- content type
- expected size
- available disk space
During download it can display:
- progress
- transferred size
- speed
- ETA
A SHA-256 digest can be generated after completion.
Downloader Security
The server-side downloader includes SSRF protections.
It rejects:
- localhost
- private network targets
- link-local addresses
- internal Docker targets
- metadata endpoints
- disallowed ports
- unsafe redirect targets
Download size and minimum remaining disk-space limits are enforced.
Telegram File Manager
Two controlled storage areas are exposed to the bot:
/srv/downloads
/srv/uploads
From Telegram it is possible to:
- list files
- inspect file size and modification time
- calculate SHA-256
- send a file back through Telegram
- delete files
- clean download/upload areas
Critical Linux directories are not writable through the file manager.
Automatic Alerts
V5 can generate alerts for:
- high CPU
- high RAM
- high swap
- high disk usage
- high temperature
- high load
- internet outage
- internet recovery
- public IP change
- container state changes
- Docker health changes
- container restart count increases
- undervoltage
- throttling
- frequency capping
- failed systemd services
- service recovery
- SMART health problems
Recovery notifications can also be generated when a metric returns to normal.
SSD-Friendly Design
Because the project runs on an SSD-backed Raspberry Pi server, minimizing unnecessary disk writes became an explicit design goal.
V5 uses:
- read-only container root filesystem
- tmpfs for temporary files
WARNINGas the default Python log level- no continuous telemetry database
- bounded important-event history
- RAM-based disk-write sampling
- Docker
locallogging driver - aggressive log rotation
- optional SMART polling
Example:
logging:
driver: local
options:
max-size: "2m"
max-file: "2"
The monitoring tool itself should not become a major source of storage wear.
Security Architecture
Pi Assistant performs powerful operations, so security is treated as part of the application architecture.
Authorized Telegram User
Only the configured ALLOWED_USER_ID is allowed to use the management interface.
No Arbitrary Shell
Pi Assistant intentionally does not provide unrestricted Telegram-to-shell execution.
Restricted SSH Gateway
Host-level operations can use:
Telegram
│
▼
Pi Assistant
│
▼
Restricted SSH User
│
▼
Forced Command Gateway
│
▼
Allowlist
│
▼
Host Helper
This allows specific host operations without exposing an unrestricted root shell.
Confirmation Tokens
Critical actions require short-lived, single-use confirmation tokens.
Examples include:
- reboot
- shutdown
- Docker recreate
- bulk updates
- cleanup
- SMART tests
- service restart
- file deletion
Technologies
The project uses:
- Python
- Docker
- Docker Compose
- Docker Engine API
- Docker SDK for Python
- Raspberry Pi OS
- Linux
/proc - Linux
/sys - psutil
- Telegram Bot API
- python-telegram-bot
- Portainer
- systemd
- journalctl
- smartmontools
- vcgencmd
- SSH
- Speedtest CLI
- Git
- GitHub
Architecture
Telegram
│
▼
Telegram Bot API
│
▼
Pi Assistant Loruv V5
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
System Monitor Docker Engine File Manager
│ │ │
│ │ ├── Downloads
│ │ └── Uploads
│ │
│ ├── Containers
│ ├── Images
│ ├── Networks
│ ├── Volumes
│ ├── Updates
│ └── Cleanup
│
├── /host/proc
├── /host/sys
├── Network
├── Disk I/O
└── Health
│
▼
Restricted SSH Gateway
│
┌───────────────┼───────────────┐
▼ ▼ ▼
SMART systemd vcgencmd
│
▼
Raspberry Pi Host
GitHub Repository
The complete source code, Docker configuration and installation documentation are available on GitHub:
github.com/emrecagri/Pi-Assistant-Loruv
What I Learned
Pi Assistant Loruv became much more than a Telegram bot project.
During development I worked with:
- Docker Engine API
- container lifecycle management
- Linux host process visibility
/procand/sys- asynchronous Python
- Telegram inline keyboards
- callback-based UI design
- event-driven monitoring
- threshold alerts
- network diagnostics
- SMART
- systemd
- restricted SSH
- SSRF protection
- file transfer
- image update workflows
- rollback strategies
- disk I/O optimization
- SSD-friendly logging
- Portainer repository deployments
- self-hosted infrastructure security
Each major feature was added because of a real operational need in my own home-server environment.
Final Result
Pi Assistant Loruv started as a simple way to check Raspberry Pi temperature, memory usage and Docker status through Telegram.
With V5 it has evolved into a broader self-hosted management assistant combining:
- system monitoring
- real host process inspection
- Docker management
- update scanning
- port analysis
- SSD/SMART monitoring
- network diagnostics
- systemd monitoring
- file transfer
- URL downloads
- automated alerts
- host management
- controlled high-risk actions
within a single Telegram interface.
A key design goal remains unchanged: the assistant should stay lightweight, consume very few resources and generate as little unnecessary SSD write activity as possible.
Bir yanıt yazın