β Clear separation of concerns
β No circular imports
β Easy to reason about
telegram-bot/
βββ bot.py
βββ requirements.txt
βββ README.md
βββ .gitignore
βββ .*.session # β not committed (server only)
βββ .env # β not committed (server only)
β
βββ config/
β βββ __init__.py
β βββ env.py
β βββ forwarding.py
β βββ moderation.py
β
βββ core/
β βββ __init__.py
β βββ client.py
β βββ startup.py
β
βββ handlers/
β βββ __init__.py
β βββ forward.py
β βββ moderation.py
β
βββ utils/
β βββ __init__.py
β βββ logger.py
β βββ messages.py
β
βββ systemd/
β βββ telegram-bot.service
β βββ telegram-bot-update.service
β βββ telegram-bot-update.timer
β βββ update.sh
β
βββ venv/ # β not committed (server only)
β .env ignored in Git
β Telethon session files ignored
β Dedicated Telegram account (best practice)
β No hardcoded secrets
β Non-root systemd execution
config/env.py
β Validates API_ID / API_HASH
β Defaults handled safely
β Clean env loading config/forwarding.py
β Explicit channel β topic mapping
β Media-only channel rules
β Extension whitelist config/moderation.py
β Topic-specific rules
β Clear permission model
core/client.py
β Single shared client
β Correct session usage core/startup.py
β Graceful shutdown (SIGTERM / SIGINT)
β systemd-friendly
β Clean disconnect
β Proper exit codes
handlers/forward.py
β Only listens to configured source channels
β Album forwarding supported
β Media filtering enforced
β Edit β delete & repost implemented
β FloodWait-safe
β Exception-isolated
β Forward tracking prevents duplicates
handlers/moderation.py
β Topic-based rules
β Bot exempt
β Anonymous admins exempt
β Correct forum topic detection
β Safe deletes
β Temporary reason messages
β Clean logging
utils/messages.py
β Markdown-safe
β User mention safe
β Auto-delete TTL
β Exception-proof
β No UX regressions
utils/logger.py
β Single named logger
β No duplicate handlers
β Journal-friendly output
β Readable format
systemd/update.sh
β Pulls only when changes exist
β No unnecessary restarts
β Virtualenv safe
β Clear logs
β Fail-fast scripting telegram-bot-update.timer
β Hourly checks (safe)
β Persistent
β Low wake-ups telegram-bot-update.service
β Sandboxed
β No system file access
β Network-aware
telegram-bot.service
β Non-root user
β Auto-restart
β Crash protection
β Clean shutdown integration
β Journal logging
requirements.txt
β Minimal
β Correct versions implied
β No unused libraries
Actual usage:
~17 source channels
~5 messages/day
Bot can safely handle:
β 10Γ load (as per 17 source channels & 5 messages/day)
β 24Γ7 uptime
β Long-running sessions
Scenario Outcome
Bot crash systemd restart
Telegram disconnect auto reconnect
FloodWait waits & resumes
Bad message isolated
Bad album skipped
Edit storm safe repost
Update failure no restart
ssh <PRIVATE_KEY> ubuntu@<SERVER_IP>
Update server & install dependencies:
sudo apt update && sudo apt upgrade -y
sudo apt install git python3 python3-pip python3-venv -y
If repo is not cloned
cd /home/ubuntu
git clone https://github.com/DineshValor/telegram-bot.git
If already cloned
cd /home/ubuntu/telegram-bot
git pull origin master
cd /home/ubuntu/telegram-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
deactivate
cp /home/ubuntu/telegram-bot/.env.example /home/ubuntu/telegram-bot/.env
nano /home/ubuntu/telegram-bot/.env
sudo chmod +x /home/ubuntu/telegram-bot/systemd/update.sh
sudo chmod +x /home/ubuntu/telegram-bot/systemd/journal-watcher.sh
Verify:
ls -l /home/ubuntu/telegram-bot/systemd/update.sh
ls -l /home/ubuntu/telegram-bot/systemd/journal-watcher.sh
You should see -rwx.
cd /home/ubuntu/telegram-bot
source venv/bin/activate
python3 bot.py
CTRL+C (Key Press)
Systemd cannot read files from your repo directly. We must copy them.
sudo cp /home/ubuntu/telegram-bot/systemd/telegram-bot.service /etc/systemd/system/
sudo cp /home/ubuntu/telegram-bot/systemd/telegram-bot-update.service /etc/systemd/system/
sudo cp /home/ubuntu/telegram-bot/systemd/telegram-bot-update.timer /etc/systemd/system/
sudo cp /home/ubuntu/telegram-bot/systemd/telegram-bot-journal-watcher.service /etc/systemd/system/
sudo cp /home/ubuntu/telegram-bot/systemd/telegram-bot-failure.service /etc/systemd/system/
sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable telegram-bot
sudo systemctl enable telegram-bot-update.timer
sudo systemctl enable telegram-bot-journal-watcher
sudo systemctl start telegram-bot
sudo systemctl start telegram-bot-journal-watcher
sudo systemctl start telegram-bot-update.timer
systemctl status telegram-bot --no-pager
systemctl status telegram-bot-journal-watcher --no-pager
systemctl status telegram-bot-update.timer --no-pager
Run update service manually:
sudo systemctl start telegram-bot-update.service
check logs
systemctl status telegram-bot-update.service --no-pager -l
Expected behavior:
β’ If no new commit β βNo updates foundβ
β’ If new commit β pull β restart bot
journalctl -u telegram-bot -f
journalctl -u telegram-bot-update
systemctl list-timers
chmod +x /home/ubuntu/telegram-bot/systemd/update.sh
sudo systemctl daemon-reload
journalctl -u telegram-bot --no-pager
git stash
git pull
git stash pop
Start bot
sudo systemctl start telegram-bot
Restart bot
sudo systemctl restart telegram-bot
Stop bot
sudo systemctl stop telegram-bot
View logs
journalctl -u telegram-bot -f
sudo git config --global --add safe.directory /home/ubuntu/telegram-bot