Skip to content

SETUP.md

Latest commit

 

History

History
469 lines (341 loc) · 8.8 KB

SETUP.md

File metadata and controls

469 lines (341 loc) · 8.8 KB
Raw

Setup Guide - API Resource Availability Bot

Complete step-by-step guide for setting up and running the bot.

📋 Prerequisites

Before you begin, ensure you have:

Required

  • Python 3.9+ - Download Python
  • Telegram Account - For creating and using the bot
  • Internet Connection - For installing dependencies and running scans

Optional

  • Git - For cloning the repository
  • Code Editor - VSCode, PyCharm, or any preferred editor

🎯 Step 1: Get a Telegram Bot Token

  1. Open Telegram and search for @BotFather
  2. Start a chat and send /newbot
  3. Follow the instructions:
    • Choose a name for your bot (e.g., "API Checker Bot")
    • Choose a username (must end in 'bot', e.g., "api_checker_bot")
  4. BotFather will provide you with a token like: 
    123456789:ABCdefGHIjklMNOpqrsTUVwxyz
  5. Keep this token secure! Don't share it publicly.

🔧 Step 2: Setup Project

Option A: Fresh Setup

  1. Navigate to project directory
cd d:\API_Bot
  1. Create virtual environment
# Create venv
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Linux/Mac)
source venv/bin/activate

You should see (venv) in your terminal prompt.

Option B: Using existing project

If you already have the files, just activate the virtual environment:

cd d:\API_Bot
venv\Scripts\activate

📦 Step 3: Install Dependencies

With virtual environment activated:

# Upgrade pip
python -m pip install --upgrade pip

# Install all requirements
pip install -r requirements.txt

# Install Playwright browsers (required for advanced features)
playwright install chromium

Note: This may take a few minutes depending on your internet speed.

Verify Installation

python -c "import telegram; print('✅ python-telegram-bot installed')"
python -c "import httpx; print('✅ httpx installed')"
python -c "import dns.resolver; print('✅ dnspython installed')"

⚙️ Step 4: Configure Environment

  1. Create environment file
copy .env.example .env
  1. Edit .env file

Open .env in your text editor and add your bot token:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

# Database (default is fine)
DATABASE_PATH=bot_data.db

# Scanning Configuration
MAX_PARALLEL_SCANS=5
REQUEST_TIMEOUT=30
MAX_RETRIES=3

# Optional: API Keys
HAVEIBEENPWNED_API_KEY=optional_api_key

# Logging
LOG_LEVEL=INFO
LOG_FILE=bot.log

Important: Replace the bot token with your actual token from BotFather!

  1. Save the file

🚀 Step 5: Run the Bot

First Run

python bot.py

You should see:

2026-01-24 12:00:00 | INFO     | database:initialize - Database initialized successfully
2026-01-24 12:00:00 | INFO     | bot:post_init - Bot initialized successfully
2026-01-24 12:00:00 | INFO     | bot:run - Starting bot...

Test the Bot

  1. Open Telegram
  2. Search for your bot by username
  3. Start a chat and send /start
  4. You should receive the welcome message!
  5. Try sending a URL: https://google.com

✅ Step 6: Verify Everything Works

Test Commands

Send these commands to your bot:

/start    - Should show welcome message
/help     - Should show help text
/stats    - Should show statistics (0 initially)
/settings - Should show settings options

Test Scanning

Send a URL to test scanning:

https://github.com
example.com
api.telegram.org

The bot should:

  1. Show "🔄 Scanning..." message
  2. Run all checks in parallel
  3. Display formatted results
  4. Show action buttons

Test Bookmarks

  1. Scan a URL
  2. Click "🔖 Bookmark" button
  3. Send /bookmarks command
  4. You should see your saved bookmark with status indicator

🔍 Troubleshooting

Problem: "Token is invalid"

Solution:

  • Double-check your token in .env file
  • Ensure no extra spaces or quotes
  • Get a fresh token from BotFather

Problem: "ModuleNotFoundError"

Solution:

# Ensure venv is activated
venv\Scripts\activate

# Reinstall requirements
pip install -r requirements.txt

Problem: "Permission denied" or "Port already in use"

Solution:

  • Close any other instances of the bot
  • Check Task Manager for Python processes
  • Restart your terminal

Problem: Bot is slow or times out

Solution: Edit config.py:

REQUEST_TIMEOUT = 60  # Increase timeout
MAX_PARALLEL_SCANS = 3  # Reduce concurrent scans

Problem: "Playwright browsers not found"

Solution:

playwright install chromium

Problem: DNS resolution fails

Solution: Check config.py and update DNS servers:

DNS_SERVERS = ['8.8.8.8', '1.1.1.1']  # Use Google/Cloudflare DNS

🔄 Updating the Bot

To update dependencies:

pip install --upgrade -r requirements.txt

To restart the bot:

  1. Press Ctrl+C to stop
  2. Run python bot.py again

🛠️ Advanced Configuration

Custom DNS Servers

Edit config.py:

DNS_SERVERS = [
    '8.8.8.8',      # Google
    '1.1.1.1',      # Cloudflare
    '208.67.222.222' # OpenDNS
]

Adjust Timeouts

DNS_TIMEOUT = 5
HTTP_TIMEOUT = 30
SSL_TIMEOUT = 10

Rate Limiting

RATE_LIMIT_REQUESTS = 10  # Requests
RATE_LIMIT_PERIOD = 60    # Per 60 seconds

Enable Debug Logging

In .env:

LOG_LEVEL=DEBUG

📊 Database Management

View Database

The bot uses SQLite. You can view it with:

# Install SQLite browser
pip install sqlitebrowser

# Or use command line
sqlite3 bot_data.db

SQL queries:

-- View bookmarks
SELECT * FROM bookmarks;

-- View scan history
SELECT * FROM scan_history LIMIT 10;

-- View user preferences
SELECT * FROM user_preferences;

Backup Database

copy bot_data.db bot_data_backup.db

Reset Database

del bot_data.db
python bot.py  # Will recreate with fresh tables

🚀 Running in Production

Using Screen (Linux)

screen -S apibot
python bot.py
# Press Ctrl+A, then D to detach

To reattach:

screen -r apibot

Using nohup (Linux)

nohup python bot.py > bot.log 2>&1 &

Using systemd (Linux)

Create /etc/systemd/system/apibot.service:

[Unit]
Description=API Resource Availability Bot
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/API_Bot
Environment="PATH=/path/to/API_Bot/venv/bin"
ExecStart=/path/to/API_Bot/venv/bin/python bot.py
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable apibot
sudo systemctl start apibot

Using PM2 (Node.js ecosystem)

npm install -g pm2
pm2 start bot.py --name apibot --interpreter python
pm2 save
pm2 startup

🔒 Security Best Practices

  1. Never commit .env file - It's in .gitignore
  2. Use environment variables for sensitive data
  3. Restrict database file permissions
chmod 600 bot_data.db  # Linux
  1. Keep dependencies updated
pip list --outdated
pip install --upgrade package_name
  1. Monitor logs regularly
tail -f bot.log

📈 Monitoring

Check if bot is running

# Windows
tasklist | findstr python

# Linux
ps aux | grep bot.py

Monitor logs in real-time

# Windows (PowerShell)
Get-Content bot.log -Wait -Tail 50

# Linux
tail -f bot.log

Check database size

# Windows
dir bot_data.db

# Linux
ls -lh bot_data.db

🆘 Getting Help

If you encounter issues:

  1. Check logs: bot.log contains detailed error information
  2. Enable debug mode: Set LOG_LEVEL=DEBUG in .env
  3. Test components individually: Run scanner modules separately
  4. Check dependencies: Ensure all packages are installed
  5. Verify credentials: Double-check bot token

Testing Individual Components

# Test availability checker
from scanners.availability_checker import AvailabilityChecker
import asyncio

async def test():
    checker = AvailabilityChecker()
    result = await checker.check('https://google.com')
    print(result)

asyncio.run(test())

✨ Next Steps

Once your bot is running:

  1. ✅ Test all features thoroughly
  2. ✅ Customize messages in config.py
  3. ✅ Adjust timeouts and limits for your needs
  4. ✅ Set up automated backups
  5. ✅ Monitor performance and logs
  6. ✅ Share your bot with users!

📚 Additional Resources

Your bot should now be fully operational! 🎉

Send a URL to your bot and watch it analyze! If you have any issues, refer to the troubleshooting section above.