Installation & Setup

This guide covers everything you need to install and configure PFP Checker, from development environments to production deployments.

System Requirements

Docker Installation (Recommended)

Docker: Version 20.10 or higher
Docker Compose: Version 2.0 or higher
Storage: Minimum 500MB for images and database
Memory: 256MB RAM minimum (512MB recommended)

Manual Installation

Rust: Version 1.86 or newer
SQLite: Version 3.35 or higher
Operating System: Linux, macOS, or Windows
Storage: Minimum 500MB for images and database
Memory: 256MB RAM minimum (512MB recommended)

Required API Keys

Before installation, obtain these credentials:

Discord Bot Token

Go to the Discord Developer Portal
Create a new application or select an existing one
Navigate to the Bot section
Click Reset Token and copy the token

Keep your Discord token secret! Never commit it to version control or share it publicly.

ImgBB API Key

Visit ImgBB API
Sign up or log in to your account
Copy your API key from the dashboard

ImgBB offers a free tier with 150 uploads per hour, which is sufficient for most use cases.

Installation Methods

Docker (Recommended)
Manual Installation

Docker provides the easiest and most reliable installation method.

Step 1: Install Docker

If you don’t have Docker installed:

# Update package list
sudo apt-get update

# Install Docker
sudo apt-get install -y docker.io docker-compose

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional, avoids using sudo)
sudo usermod -aG docker $USER

Step 2: Clone the Repository

git clone https://github.com/j4ytr1n1ty/pfp-checker.git
cd pfp-checker

Step 3: Configure Environment Variables

Create your .env file from the example:

cp .env.example .env

Edit the .env file with your credentials:

.env

DISCORD_TOKEN=your_discord_bot_token_here
IMGBB_KEY=your_imgbb_api_key_here
DATABASE_URL=sqlite:database.sqlite

The DATABASE_URL should remain as sqlite:database.sqlite unless you have a specific reason to change it.

Step 4: Start the Bot

# Start in detached mode (runs in background)
docker-compose up -d

# View logs to verify it's working
docker-compose logs -f

You should see output indicating the bot has connected:

pfp-checker | PFP Checker is connected!
pfp-checker | Updated Global Application Commands

Step 5: Verify Installation

In Discord, invite your bot to a server and run:

/ping

If you receive a response showing latency, your installation is successful!

Managing the Docker Container

# Stop the bot
docker-compose down

# Restart the bot
docker-compose restart

# View logs
docker-compose logs -f

# Update to latest version
git pull
docker-compose down
docker-compose up -d --build

For users who prefer to run PFP Checker without Docker.

Step 1: Install Rust

# Install Rust using rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Restart your terminal or run:
source $HOME/.cargo/env

# Verify installation
rustc --version  # Should show 1.86 or higher

Step 2: Install SQLite

sudo apt-get update
sudo apt-get install -y sqlite3 libsqlite3-dev

Step 3: Clone and Build

# Clone repository
git clone https://github.com/j4ytr1n1ty/pfp-checker.git
cd pfp-checker

# Install SQLx CLI for migrations
cargo install sqlx-cli --no-default-features --features sqlite

# Build the project (this may take a few minutes)
cargo build --release

Step 4: Configure Environment

# Create environment file
cp .env.example .env

# Edit with your credentials
nano .env  # or use your preferred editor

Your .env should contain:

.env

DISCORD_TOKEN=your_discord_bot_token_here
IMGBB_KEY=your_imgbb_api_key_here
DATABASE_URL=sqlite:database.sqlite

Step 5: Run the Bot

# Run directly
./target/release/pfp-checker

# Or run in development mode
cargo run

The database and migrations are handled automatically on first run. You don’t need to run sqlx database setup manually.

Running as a Service (Linux)

For production deployments, create a systemd service:

# Create service file
sudo nano /etc/systemd/system/pfp-checker.service

Add the following content:

/etc/systemd/system/pfp-checker.service

[Unit]
Description=PFP Checker Discord Bot
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/pfp-checker
ExecStart=/path/to/pfp-checker/target/release/pfp-checker
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

# Reload systemd
sudo systemctl daemon-reload

# Enable on boot
sudo systemctl enable pfp-checker

# Start the service
sudo systemctl start pfp-checker

# Check status
sudo systemctl status pfp-checker

# View logs
sudo journalctl -u pfp-checker -f

Environment Variables

PFP Checker uses three environment variables for configuration:

Variable	Required	Description	Example
`DISCORD_TOKEN`	Yes	Your Discord bot token from the Developer Portal	`MTIzNDU2Nzg5MDEyMzQ1Njc4OTAuGxY...`
`IMGBB_KEY`	Yes	Your ImgBB API key for image hosting	`a1b2c3d4e5f6g7h8i9j0`
`DATABASE_URL`	Yes	SQLite database file path	`sqlite:database.sqlite`

All three environment variables are required. The bot will fail to start if any are missing.

Database Setup

PFP Checker uses SQLite with automatic schema migrations managed by SQLx.

Automatic Migrations

On startup, the bot automatically:

Creates the database file if it doesn’t exist (specified in DATABASE_URL)
Runs all pending migrations from the migrations/ directory
Creates the necessary tables:
- User - Stores monitored users and tracking start dates
- ProfilePicture - Archives profile pictures with checksums and ImgBB links
- UsernameChange - Records username changes with timestamps
- Server - Stores monitored servers
- ServerPicture - Archives server icon changes

Database Location

By default, the database is stored as database.sqlite in the project root. To change this:

.env

# Store in a different location
DATABASE_URL=sqlite:/var/lib/pfp-checker/database.sqlite

# Or use a relative path
DATABASE_URL=sqlite:data/pfp-checker.db

Ensure the directory exists and the bot has write permissions to the database file location.

Database Backups

Regularly backup your database to prevent data loss:

# Simple copy backup
cp database.sqlite database.backup.sqlite

# With timestamp
cp database.sqlite "database.backup.$(date +%Y%m%d-%H%M%S).sqlite"

# Automated daily backup (cron)
0 2 * * * cp /path/to/database.sqlite /backups/pfp-checker-$(date +\%Y\%m\%d).sqlite

Discord Bot Configuration

Required Bot Permissions

When inviting the bot to your server, it only needs:

View Channels: To receive commands
Use Application Commands: To register and respond to slash commands

The bot does NOT require:

Message Content Intent
Server Members Intent
Presence Intent

Generating Invite URL

Go to Discord Developer Portal
Select your application
Navigate to OAuth2 → URL Generator
Select scopes: bot and applications.commands
Select bot permissions: View Channels
Copy the generated URL

The bot automatically registers all slash commands globally when it starts. There’s no need to manually register commands.

Verification Steps

After installation, verify everything works correctly:

Check Bot Status

Verify the bot appears online in your Discord server’s member list.

Test Ping Command

Run /ping to ensure the bot responds with latency information.

Test Monitoring

Run /monitor @user on yourself or another user.You should receive a confirmation message.

Verify Database Creation

Check that database.sqlite exists in your project directory (or the path specified in DATABASE_URL).

Check Logs

Review logs for any errors:

docker-compose logs -f

Wait for First Update

After 30 minutes, run /pfphistory @user on a monitored user.You should see at least one profile picture entry.

Troubleshooting

Bot doesn’t start

Check environment variables:

# Verify .env file exists and has correct values
cat .env

Common issues:

Missing DISCORD_TOKEN or IMGBB_KEY
Invalid Discord token (reset it in Developer Portal)
Database file location not writable

Commands not appearing

Wait 1-5 minutes after starting the bot for Discord to register global commands. If commands still don’t appear:

Remove and re-invite the bot with the correct OAuth2 URL
Ensure you selected both bot and applications.commands scopes
Restart the bot

Database migration errors

# Check database file permissions
ls -la database.sqlite

# Ensure the directory exists
mkdir -p $(dirname database.sqlite)

Image upload failures

Verify ImgBB API key:

Check that IMGBB_KEY in .env is correct
Verify you haven’t exceeded ImgBB rate limits (150 uploads/hour)
Test your API key: curl "https://api.imgbb.com/1/upload?key=YOUR_KEY"

High memory usage

PFP Checker is designed to be lightweight, but if you experience high memory usage:

Check how many users/servers you’re monitoring
Review log files for errors or excessive logging
Restart the bot to clear any memory leaks

Production Deployment

For production environments, consider:

Docker Compose with Auto-Updates

The project includes a production Docker Compose configuration with Watchtower for automatic updates:

docker-compose -f docker-compose.production.yml up -d

Security Best Practices

Store .env outside the project directory with restricted permissions:
```
chmod 600 /etc/pfp-checker/.env
```
Use environment-specific .env files (development, production)
Regularly update dependencies: cargo update
Monitor logs for suspicious activity
Implement database backup automation

Monitoring

Set up monitoring to ensure your bot stays healthy:

# Health check script
#!/bin/bash
if ! docker-compose ps | grep -q "Up"; then
    docker-compose up -d
    echo "Bot restarted at $(date)" >> /var/log/pfp-checker-restarts.log
fi

Run via cron every 5 minutes:

*/5 * * * * /path/to/health-check.sh

Getting Started

Deployment

User Guide

Commands

​Installation & Setup

​System Requirements

​Docker Installation (Recommended)

​Manual Installation

​Required API Keys

​Installation Methods

​Step 1: Install Docker

​Step 2: Clone the Repository

​Step 3: Configure Environment Variables

​Step 4: Start the Bot

​Step 5: Verify Installation

​Managing the Docker Container

​Step 1: Install Rust

​Step 2: Install SQLite

​Step 3: Clone and Build

​Step 4: Configure Environment

​Step 5: Run the Bot

​Running as a Service (Linux)

​Environment Variables

​Database Setup

​Automatic Migrations

​Database Location

​Database Backups

​Discord Bot Configuration

​Required Bot Permissions

​Generating Invite URL

​Verification Steps

​Troubleshooting

​Bot doesn’t start

​Commands not appearing

​Database migration errors

​Image upload failures

​High memory usage

​Production Deployment

​Docker Compose with Auto-Updates

​Security Best Practices

​Monitoring

​Next Steps

User Tracking Guide

Server Tracking Guide

Build docs developers (and LLMs) love

Installation & Setup

System Requirements

Docker Installation (Recommended)

Manual Installation

Required API Keys

Installation Methods

Step 1: Install Docker

Step 2: Clone the Repository

Step 3: Configure Environment Variables

Step 4: Start the Bot

Step 5: Verify Installation

Managing the Docker Container

Step 1: Install Rust

Step 2: Install SQLite

Step 3: Clone and Build

Step 4: Configure Environment

Step 5: Run the Bot

Running as a Service (Linux)

Environment Variables

Database Setup

Automatic Migrations

Database Location

Database Backups

Discord Bot Configuration

Required Bot Permissions

Generating Invite URL

Verification Steps

Troubleshooting

Bot doesn’t start

Commands not appearing

Database migration errors

Image upload failures

High memory usage

Production Deployment

Docker Compose with Auto-Updates

Security Best Practices

Monitoring

Next Steps