Skip to main content
Docker is the recommended way to deploy PFP Checker. It provides a consistent environment and simplifies deployment with automatic database migrations.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Quick Start

1

Clone the repository

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

Create environment configuration

Copy the example environment file and configure your credentials:
cp .env.example .env
Edit .env and add your tokens:
.env
DISCORD_TOKEN=<your-discord-bot-token>
IMGBB_KEY=<your-imgbb-api-key>
DATABASE_URL=sqlite:database.sqlite
3

Start the bot

Launch the bot using Docker Compose:
docker-compose up -d
The bot will:
  • Build the Docker image from the Dockerfile
  • Create a persistent volume for the database
  • Run database migrations automatically
  • Start the bot in detached mode
4

Verify the deployment

Check that the container is running:
docker-compose ps
View the logs:
docker-compose logs -f
You should see a message indicating the bot is connected.

​
Docker Configuration

​
Dockerfile Overview

The Dockerfile uses a multi-stage build for optimal image size: 
# Build stage
FROM rust:1.86-slim-bullseye AS builder

# Install required dependencies
RUN apt-get update && \
  apt-get install -y \
  pkg-config \
  libssl-dev \
  sqlite3 \
  libsqlite3-dev \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /usr/src/app
COPY . .

# Build the project with release optimizations
RUN cargo build --release

# Runtime stage
FROM debian:bullseye-slim

# Install runtime dependencies
RUN apt-get update && \
  apt-get install -y \
  ca-certificates \
  sqlite3 \
  libsqlite3-0 \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy the built binary from builder
COPY --from=builder /usr/src/app/target/release/pfp-checker /app/pfp-checker
# Copy migrations folder
COPY --from=builder /usr/src/app/migrations /app/migrations

# Create volume for persistent database storage
VOLUME ["/app/data"]

# Set environment variables
ENV DATABASE_URL=sqlite:/app/data/database.sqlite

# Run the binary
CMD ["./pfp-checker"]

​
Docker Compose Configurations

services:
  discord-bot:
    build: .
    container_name: pfp_spy
    env_file:
      - .env
    volumes:
      - "./data:/app/data"
    restart: unless-stopped
    environment:
      - DATABASE_URL=/app/data/database.sqlite

​
Volume Persistence

The bot uses a volume mount to persist the SQLite database across container restarts: 
volumes:
  - "./data:/app/data"
Database Location: The database file is stored at ./data/database.sqlite on your host machine and mounted to /app/data/database.sqlite inside the container.
This ensures that:
  • User tracking data persists across container restarts
  • Profile picture history is preserved
  • Database migrations are applied correctly

​
Production Deployment

For production environments, use the production Docker Compose configuration: 
docker-compose -f docker-compose.production.yml up -d

​
Production Features

Pre-built Images

Uses the official image from GitHub Container Registry instead of building locally

Auto-updates

Watchtower automatically checks for and deploys new versions every 5 minutes

Auto-restart

Containers automatically restart on failure or system reboot

Security

Watchtower runs with security restrictions (no-new-privileges)
Watchtower Configuration: The Watchtower service runs with user 1000:1000. Adjust this to match your system’s user ID if needed using id -u and id -g.

​
Managing the Container

​
View Logs

# Follow logs in real-time
docker-compose logs -f

# View last 100 lines
docker-compose logs --tail=100

# View logs for specific service
docker-compose logs discord-bot

​
Stop the Bot

# Stop without removing containers
docker-compose stop

# Stop and remove containers
docker-compose down

​
Restart the Bot

# Restart all services
docker-compose restart

# Restart specific service
docker-compose restart discord-bot

​
Updating the Container

If you’re using the production configuration with Watchtower, updates are automatic:
  • Watchtower checks for new images every 5 minutes (300 seconds)
  • When a new version is detected, it automatically pulls and restarts the container
  • Your data is preserved during updates
Check Watchtower logs to see update activity:
docker-compose -f docker-compose.production.yml logs watchtower

​
Troubleshooting

Check the logs for configuration errors:
docker-compose logs discord-bot
Common issues:
  • Invalid Discord token or ImgBB API key
  • Missing .env file
  • Database connection errors
Ensure the volume mount is correct:
# Check if data directory exists
ls -la ./data

# Verify volume mount
docker inspect pfp_spy | grep -A 10 Mounts
Fix permissions on the data directory:
# Create data directory if it doesn't exist
mkdir -p ./data

# Set proper permissions
chmod 755 ./data
Check Watchtower logs and ensure it has Docker socket access:
docker-compose -f docker-compose.production.yml logs watchtower

# Verify Docker socket mount
docker inspect <watchtower-container-id> | grep -A 5 Mounts

​
Next Steps

Configuration

Learn about all available environment variables and configuration options

Manual Installation

Prefer to run without Docker? Check out the manual installation guide

Build docs developers (and LLMs) love

Get started for freeTalk to us