Skip to content

HOW-TO-RESTART.md

Latest commit

 

History

History
301 lines (217 loc) · 8.86 KB

HOW-TO-RESTART.md

File metadata and controls

301 lines (217 loc) · 8.86 KB

Operations & Recovery Guide

Restart, redeploy, and troubleshoot your SCI Case Tracker bot. Works for the standalone Telegram bot (bot/telegram_bot.py) and the FastAPI service (api/main.py).

Quick reference

# Status
systemctl --user status sci-bot

# Start / stop / restart
systemctl --user start sci-bot
systemctl --user stop sci-bot
systemctl --user restart sci-bot

# Live logs (recommended — captures stderr too)
journalctl --user -u sci-bot -f

# Disable auto-start (without stopping the running bot)
systemctl --user disable sci-bot
systemctl --user enable sci-bot

Recommended setup — systemd user service

Once configured, the bot starts on every login (and on every boot if you enable lingering). No manual restart needed.

1. Drop the unit file

Save as ~/.config/systemd/user/sci-bot.service:

[Unit]
Description=SCI Case Tracker — Telegram bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=%h/sci-case-tracker
EnvironmentFile=%h/sci-case-tracker/.env
ExecStart=%h/sci-case-tracker/.venv/bin/python -m bot.telegram_bot
Restart=on-failure
RestartSec=5
StandardOutput=append:%h/sci-case-tracker/logs/bot.log
StandardError=append:%h/sci-case-tracker/logs/bot.log
Environment=SCI_CACHE_DB=%h/sci-case-tracker/src/sci_case_tracker/cache.db
Environment=SCI_BOT_DB=%h/sci-case-tracker/bot/watchlist.db

[Install]
WantedBy=default.target

%h expands to your home directory at runtime.

2. Create the .env file (next to the repo)

cp ~/sci-case-tracker/.env.example ~/sci-case-tracker/.env
# Open ~/sci-case-tracker/.env and paste your TELEGRAM_BOT_TOKEN

3. Make sure the log directory exists

mkdir -p ~/sci-case-tracker/logs

4. Enable + start

systemctl --user daemon-reload
systemctl --user enable sci-bot.service
systemctl --user start sci-bot.service
systemctl --user status sci-bot.service

You should see:

● sci-bot.service - SCI Case Tracker — Telegram bot
   Active: active (running)
   Main PID: <some-pid>

5. Survive reboots without logging in

By default, systemd user services only run while you're logged in. To keep the bot running across reboots even before login, enable lingering:

sudo loginctl enable-linger $USER

One-time setup. From this point on, the bot starts at boot.

Manual restart (no systemd)

If you don't have systemd or prefer manual control:

# Stop anything that might already be running
pkill -f "bot.telegram_bot"; sleep 2

# Start in background, detached from terminal
TOKEN=$(grep '^TELEGRAM_BOT_TOKEN=' ~/sci-case-tracker/.env | cut -d= -f2-)
TELEGRAM_BOT_TOKEN="$TOKEN" \
  setsid bash -c "cd ~/sci-case-tracker && exec .venv/bin/python -m bot.telegram_bot" \
  </dev/null \
  >~/sci-case-tracker/logs/bot.log \
  2>&1 \
  & disown

# Verify
sleep 5
ps aux | grep "bot.telegram_bot" | grep -v grep
tail -10 ~/sci-case-tracker/logs/bot.log

You should see SCI Telegram bot online. Open mode: <True|False> in the log.

What persists across reboot

Data Location Notes
Source code ~/sci-case-tracker/ tracked in git
Python venv + deps ~/sci-case-tracker/.venv/ recreate with pip install -r requirements.txt
SCI status cache (SQLite) ~/sci-case-tracker/src/sci_case_tracker/cache.db warm cache survives — re-lookups are instant
Per-user watchlist (SQLite) ~/sci-case-tracker/bot/watchlist.db /track and /list data
Bot token ~/sci-case-tracker/.env gitignored
Bot logs ~/sci-case-tracker/logs/bot.log trim periodically; systemd captures via journald too
systemd unit ~/.config/systemd/user/sci-bot.service survives reinstalls of the repo

Updating to a newer version

systemctl --user stop sci-bot
cd ~/sci-case-tracker
git pull
.venv/bin/pip install -r requirements.txt --upgrade
.venv/bin/pip install -e . --upgrade
systemctl --user start sci-bot
journalctl --user -u sci-bot -n 30

Cache and watchlist DBs survive updates. Schema changes (rare) ship with a migration script in the release notes.

Common issues

Bot doesn't reply to anything

  1. Is it actually running? 
    ps aux | grep "bot.telegram_bot" | grep -v grep
systemctl --user status sci-bot
  2. Is something else polling the same Telegram token? Telegram only allows one poller per bot. Check for any other bot framework you might be running.
  3. Check the log for errors: 
    journalctl --user -u sci-bot -n 100
# or
tail -100 ~/sci-case-tracker/logs/bot.log
  4. If Open mode: False in the log and you're not in TELEGRAM_ALLOWED_USERS, the bot ignores you silently. Add your Telegram user ID to the env var (find your ID by messaging @userinfobot).

ModuleNotFoundError: No module named 'bot'

You started the bot from the wrong directory. The bot package needs to be discoverable from cwd. Always cd ~/sci-case-tracker first, or use the systemd unit (it sets WorkingDirectory).

ModuleNotFoundError: No module named 'pdfplumber' (or openpyxl/docx)

Install the document-extractor dependencies:

~/sci-case-tracker/.venv/bin/pip install -r ~/sci-case-tracker/requirements.txt

Image uploads fail with tesseract not found

OCR needs the Tesseract system package:

sudo apt install -y tesseract-ocr        # Debian / Ubuntu
brew install tesseract                    # macOS

No bot restart needed — Python imports tesseract at OCR time, not at startup.

503 or timeout errors from sci.gov.in

The SCI portal goes down occasionally for maintenance. The client retries once automatically. If you see persistent 5xx errors:

curl -I https://www.sci.gov.in/

If that fails too, wait 5-10 minutes and try again. SCI's side is the bottleneck.

Two sendDocument events but only one file shows in Telegram

Telegram may collapse identical files (same hash). Try with a different filename or a tiny modification.

Concurrent uploads block each other

If you find a long batch upload blocks new messages, ensure the bot was started after concurrent updates were enabled. The current code uses Application.builder().concurrent_updates(True) — if you've forked an older copy, update.

Switching between v0.2 (file uploads) and v0.1 (text-only)

If you ever want to roll back to v0.1.0:

systemctl --user stop sci-bot
cd ~/sci-case-tracker
git checkout v0.1.0
.venv/bin/pip install -r requirements.txt --upgrade
.venv/bin/pip install -e . --upgrade
systemctl --user start sci-bot

To return to latest:

systemctl --user stop sci-bot
git checkout main
git pull
.venv/bin/pip install -r requirements.txt --upgrade
.venv/bin/pip install -e . --upgrade
systemctl --user start sci-bot

Recovery prompt for AI assistants

If you use Claude / ChatGPT / Codex to manage your server, paste this into a fresh session to get the bot running again:

Resume my SCI Case Tracker Telegram bot.

Expected state:
- Repo at ~/sci-case-tracker (https://github.com/CyberWarrior9/sci-case-tracker)
- venv at ~/sci-case-tracker/.venv with sci-case-tracker installed
- Bot token in ~/sci-case-tracker/.env (TELEGRAM_BOT_TOKEN=...)
- Optional systemd unit at ~/.config/systemd/user/sci-bot.service

Please:
1. Verify the repo is present and pull latest from origin/main
2. Confirm only one bot process is running (don't start a duplicate)
3. If the systemd unit exists, use `systemctl --user start sci-bot`;
   otherwise start manually using the commands in HOW-TO-RESTART.md
4. Tail logs for 5 seconds and confirm the bot is online
5. Report PID and how to test (send any case number in Telegram)

Bot management cheat sheet

Goal Command
Is it running? systemctl --user is-active sci-bot
Start it systemctl --user start sci-bot
Stop it systemctl --user stop sci-bot
Restart it systemctl --user restart sci-bot
Live tail logs journalctl --user -u sci-bot -f
Last 50 log lines journalctl --user -u sci-bot -n 50
Filter errors journalctl --user -u sci-bot | grep -iE "error|exception|fail"
Auto-start on boot systemctl --user enable sci-bot
Survive logout sudo loginctl enable-linger $USER (one-time)
Disable auto-start systemctl --user disable sci-bot

When to file an issue

Open an issue on the repo if:

  • The bot crashes repeatedly with the same error in logs
  • A specific case number returns wrong data (paste the case number + what came back)
  • A specific file format isn't being parsed (attach a sanitised sample)
  • A new SCI case type isn't recognised (paste the format you're trying)

Don't open an issue for:

  • Generic Python or Telegram bot setup questions (use Stack Overflow)
  • "How do I deploy this to AWS / Heroku / X" (check docs/DEPLOY.md)
  • Feature requests for non-SCI courts (a wider rewrite — file under Discussions instead)