Running the Bot

Starting the Bot

Once you’ve installed and configured JackettSearchBot, you can start it with:

uv run python main.py

Using uv run ensures the correct virtual environment is used without manual activation.

Startup Process

When the bot starts, it goes through several initialization steps:

Load configuration

The bot loads config.env and validates all required variables.From main.py:4-9:

try:
    bot = JackettSearchBot.initialize("config.env")
except ValueError as exc:
    print(f"Initialization failed: {exc}")
    print("Please fill the missing values in config.env and start again.")
    raise SystemExit(1) from exc

Initialize logging

The bot sets up logging with rotating file handler and console output.Log files are created at the path specified in LOG_FILE_PATH (default: logs/jackett_bot.log).

Initialize services

The bot initializes internal services:

AuthorizationService - Manages user access control
JackettService - Handles Jackett API communication
PTPService - Checks PassThePopcorn availability

Command handlers are registered for Telegram commands:

/start, /help
/release, /r (with alias /relase)
/check
/auth, /unauth, /unauthall

From app.py:56-87

Start Pyrogram client

The Telegram client connects and begins polling for messages.You’ll see:

2026-03-03 12:00:00 | INFO | JackettSearchBot | Starting bot runtime.

Successful Startup

When the bot starts successfully, you’ll see log output like:

2026-03-03 12:00:00 | INFO | JackettSearchBot | JackettSearchBot initialized.
2026-03-03 12:00:00 | INFO | JackettSearchBot | Logging configured | console=INFO | file=DEBUG | path=/home/user/JackettSearchBot/logs/jackett_bot.log
2026-03-03 12:00:00 | INFO | JackettSearchBot | Initialization complete. Configuration is valid.
2026-03-03 12:00:00 | INFO | JackettSearchBot | Starting bot runtime.

The bot is now running and ready to receive commands.

Stopping the Bot

To stop the bot gracefully:

Press Ctrl+C in the terminal
The bot will catch the interrupt signal and shut down cleanly

From app.py:89-113, the shutdown process:

try:
    self.app.run()
except KeyboardInterrupt:
    self.logger.info("Stop signal received (KeyboardInterrupt). Exiting gracefully.")
except Exception:
    self.logger.exception("Fatal runtime error. Bot stopped unexpectedly.")
    raise
finally:
    self._shutdown_services()
    self.logger.info("Bot shutdown complete.")

The bot closes all HTTP clients and cleans up resources during shutdown.

Running in Production

For production deployments, you should run the bot as a service that automatically restarts on failure.

Option 1: systemd (Linux)

Create a systemd service file at /etc/systemd/system/jackett-bot.service:

[Unit]
Description=JackettSearchBot Telegram Bot
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/JackettSearchBot
Environment="PATH=/path/to/JackettSearchBot/.venv/bin:/usr/bin"
ExecStart=/usr/local/bin/uv run python main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable jackett-bot
sudo systemctl start jackett-bot

Check status and logs:

# Check status
sudo systemctl status jackett-bot

# View logs
sudo journalctl -u jackett-bot -f

Option 2: Docker

Create a Dockerfile:

FROM python:3.11-slim

# Install uv
RUN pip install uv

# Set working directory
WORKDIR /app

# Copy project files
COPY pyproject.toml uv.lock ./
COPY jackett_bot ./jackett_bot
COPY main.py ./

# Install dependencies
RUN uv sync --frozen

# Create logs directory
RUN mkdir -p logs

# Run the bot
CMD ["uv", "run", "python", "main.py"]

Create docker-compose.yml:

version: '3.8'

services:
  jackett-bot:
    build: .
    container_name: jackett-bot
    restart: unless-stopped
    volumes:
      - ./config.env:/app/config.env:ro
      - ./logs:/app/logs
    network_mode: "host"

Run with Docker Compose:

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

When using Docker, ensure JACKETT_URL in config.env points to a reachable address. Use host.docker.internal on macOS/Windows or the host IP on Linux if Jackett is on the host machine.

Option 3: PM2 (Node.js Process Manager)

Install PM2 globally:

npm install -g pm2

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'jackett-bot',
    script: 'uv',
    args: 'run python main.py',
    cwd: '/path/to/JackettSearchBot',
    autorestart: true,
    max_restarts: 10,
    restart_delay: 5000,
    error_file: './logs/pm2-error.log',
    out_file: './logs/pm2-out.log',
  }]
};

Manage with PM2:

# Start
pm2 start ecosystem.config.js

# Monitor
pm2 monit

# View logs
pm2 logs jackett-bot

# Restart
pm2 restart jackett-bot

# Stop
pm2 stop jackett-bot

# Make it start on boot
pm2 startup
pm2 save

Monitoring and Logs

Log Files

The bot writes detailed logs to the file specified in LOG_FILE_PATH. Logs use a rotating file handler:

Max file size: 10 MB
Backup files: 5
Total storage: Up to 60 MB

From app.py:135-140:

file_handler = RotatingFileHandler(
    filename=log_path,
    maxBytes=10 * 1024 * 1024,
    backupCount=5,
    encoding="utf-8",
)

Log Format

Console logs (simpler format):

%(asctime)s | %(levelname)s | %(name)s | %(message)s

File logs (detailed format):

%(asctime)s | %(levelname)s | %(name)s | %(filename)s:%(lineno)d | %(funcName)s | %(message)s

Viewing Logs

# Tail the log file
tail -f logs/jackett_bot.log

# Search for errors
grep ERROR logs/jackett_bot.log

# View recent logs
tail -n 100 logs/jackett_bot.log

Troubleshooting

Bot Won’t Start

Symptom: Bot exits immediately after starting Solution: Check for configuration errors:

uv run python main.py

Look for validation errors about missing or invalid configuration values.

Database Locked Error

Symptom: Error message about database being locked

SQLite operational error: database is locked

Solution: From app.py:95-104, this happens when another instance is running:

Check for other running instances:
```
ps aux | grep main.py
```
Stop the other instance:
```
pkill -f "python main.py"
```
If the issue persists, remove stale session files:
```
rm -f jackett_bot.session*
```

The bot uses in_memory=True for sessions (from app.py:40-46) to avoid persistent session locks, but this error can still occur if multiple instances start simultaneously.

Connection Errors

Symptom: Cannot connect to Telegram or Jackett Solutions:

Check network connectivity:

ping api.telegram.org
curl -I $JACKETT_URL

Verify Jackett URL in config.env is correct and reachable
Check firewall rules allow outbound connections
Verify API credentials are correct and not expired

Bot Crashes or Restarts

Symptom: Bot stops unexpectedly Solution:

Check the log file for error messages:
```
tail -n 50 logs/jackett_bot.log
```
Look for patterns before crashes (specific commands, high load, etc.)
Ensure system has sufficient resources (memory, disk space)
Update dependencies:
```
uv sync
```

High Memory Usage

Symptom: Bot uses excessive memory Solutions:

Reduce MAX_RESULTS in config.env to show fewer results per page
Decrease REDACT_AFTER_SECONDS to free message data sooner

Monitor with system tools:

ps aux | grep python
top -p $(pgrep -f main.py)

Health Checks

You can verify the bot is running and responsive:

Manual Check

Send /start to the bot on Telegram. You should receive a response confirming access.

Process Check

# Check if process is running
pgrep -f "python main.py"

# Check with full details
ps aux | grep "python main.py"

Log Check

Recent log activity indicates the bot is running:

# Check last log entry
tail -n 1 logs/jackett_bot.log

# Check for recent activity
find logs/jackett_bot.log -mmin -5

Performance Tips

Use tgcrypto - Automatically installed on Python < 3.13 for better performance
Optimize MAX_RESULTS - Balance between usability and performance (recommended: 10-15)
Monitor logs - Use INFO level for console, DEBUG for files
Regular restarts - If running 24/7, restart weekly to clear accumulated state
Resource limits - Set appropriate limits in systemd or Docker to prevent resource exhaustion

Best Practices

Use a process manager

Always run the bot with a process manager (systemd, Docker, PM2) in production to ensure automatic restarts.

Monitor logs regularly

Set up log rotation and monitoring to catch issues early:

# Add to crontab
0 0 * * * find /path/to/logs -name "*.log.*" -mtime +30 -delete

Keep backups

While the bot doesn’t store persistent data, keep backups of:

config.env (securely)
Custom modifications to the code

Update regularly

Keep dependencies updated for security patches:

uv sync

Test before deploying

Always test configuration changes in a development environment first.

Next Steps

Now that your bot is running:

Learn Bot Commands - Understand how to use the bot
Project Structure - Explore the codebase structure
Best Practices - Production deployment tips

Get Started

Setup

Usage

Reference

Starting the Bot

Startup Process

Successful Startup

Stopping the Bot

Running in Production

Option 1: systemd (Linux)

Option 2: Docker

Option 3: PM2 (Node.js Process Manager)

Monitoring and Logs

Log Files

Log Format

Viewing Logs

Troubleshooting

Bot Won’t Start

Database Locked Error

Connection Errors

Bot Crashes or Restarts

High Memory Usage

Health Checks

Manual Check

Process Check

Log Check

Performance Tips

Best Practices

Next Steps

Build docs developers (and LLMs) love

Get Started

Setup

Usage

Reference

Documentation Index

​Starting the Bot

​Startup Process

​Successful Startup

​Stopping the Bot

​Running in Production

​Option 1: systemd (Linux)

​Option 2: Docker

​Option 3: PM2 (Node.js Process Manager)

​Monitoring and Logs

​Log Files

​Log Format

​Viewing Logs

​Troubleshooting

​Bot Won’t Start

​Database Locked Error

​Connection Errors

​Bot Crashes or Restarts

​High Memory Usage

​Health Checks

​Manual Check

​Process Check

​Log Check

​Performance Tips

​Best Practices

​Next Steps

Build docs developers (and LLMs) love

Starting the Bot

Startup Process

Successful Startup

Stopping the Bot

Running in Production

Option 1: systemd (Linux)

Option 2: Docker

Option 3: PM2 (Node.js Process Manager)

Monitoring and Logs

Log Files

Log Format

Viewing Logs

Troubleshooting

Bot Won’t Start

Database Locked Error

Connection Errors

Bot Crashes or Restarts

High Memory Usage

Health Checks

Manual Check

Process Check

Log Check

Performance Tips

Best Practices

Next Steps