Overview

PaperTrail is a free and open source, self-hostable Discord bot designed to deliver structured, reliable logging across all major audit and runtime events. It hooks into Discord's audit logs to cover for most of the audit log events and for events not covered by Audit Logs, it supplements them with real-time listeners to bridge gaps in native coverage (e.g. voice state, boosts, message edits and deletions, custom triggers).

Key Features:

• 🔍 Full audit log integration (supports over 50+ event types) and generic support for unknown types
• 💬 Message logging (edit, delete)
• 👤 Member activity tracking (joins, leaves, kicks, bans, updates)
• 🔊 Voice activity logging (join/leave, move)
• 🚀 Server boost tracking
• 🧱 Minimalist PostgreSQL schema with 30 day message deletion

🔐 While PaperTrail is designed to be self-hosted for maximum data ownership, a public instance is also available if preferred.

📎 Discovery Link: https://discord.com/discovery/applications/1381658412550590475

Self-Hosting Guide

Setting up the bot

Step 1: Get Required Secrets

You will need four environment variables to run the bot:

• TOKEN – Your Discord bot token from the Discord Developer Portal
• DATABASEURL – A PostgreSQL connection URL (format: jdbc:postgresql://host:port/dbname?ssl=require&user=username&password=password)
• MESSAGE_SECRET - A randomly generated secret that will be used as a passphrase for encrypting and decrypting all the messages sent to and from the database respectively
• DEVELOPER_OR_HOSTER_ID - This will be the Discord UserID of the host of this bot. This will allow the host to use the /announcement command to broadcast to all Audit-Logging channels registered in the database

💡 You will receive the DATABASEURL from your database hosting provider once you've set up your database. This value is essential and should be kept secure.

💡 You can use any passphrase generator to generate a MESSAGE_SECRET. Make sure to store it in a secure place.

Create a .env file with the following:

# .env file
TOKEN=your-discord-application-token
DATABASEURL=jdbc:postgresql://your-database-url
MESSAGE_SECRET=your-secret
DEVELOPER_OR_HOSTER_ID=your-id

⚠️ Never commit your .env file to version control. Add it to .gitignore:

.env

Step 2: Deployment Options

Fork this repository to your GitHub account, connect it to your preferred cloud platform, and configure your environment variables in the platform. Some paltform services may also support adding secrets directly from your .env file.

A. Cloud Platforms with GitHub + Docker Support

• These can auto-deploy using the included Dockerfile

B. Platforms with GitHub + Java Support (No Docker)

• These can build the project using the pom.xml if JDK 21+ is available

Build and Run (for local/manual deployment)

If deploying manually or running locally:

Build the JAR:

./mvnw clean package   # If using Maven Wrapper

OR

mvn clean package       # If Maven is installed globally

This creates a runnable JAR file in the target/ folder, named paper-trail-bot.jar.

Run the JAR:

java -jar target/paper-trail-bot.jar

Ensure you have JDK 21 or later installed.

For local deployments, make sure your .env file containing the secrets is placed in the project's base directory

Privacy

PaperTrail is built with privacy-first principles. By default, it does not log any personal data unless features are explicitly enabled by server admins.

• Messages are logged for moderation purposes only, if enabled.
• All stored messages are encrypted before being saved to the database.
• Logs are automatically deleted after 30 days.
• No personal data is used for analytics, profiling, or sold to third parties.
• If requested, users can have their data deleted by ID.

Read the full Privacy Policy

Security

If you discover a security vulnerability in PaperTrail, please report it privately.

• Do not open public GitHub issues for security bugs.
• Instead, email me at 📧 egg03@duck.com
• I will respond as soon as possible and work with you to resolve the issue.

View the full Security Policy

Terms of Use

PaperTrail is provided under the Apache 2.0 License and is intended for responsible use. By using the public instance or self-hosting it, you agree to the basic terms outlined in our Terms of Service.

License

PaperTrail is licensed under the Apache License 2.0.

You are free to:

• Use, modify, and redistribute the code
• Self-host or publicly host your own instance
• Build on top of this bot for your own projects

Just make sure to include proper attribution and comply with the terms.

---

Feel free to contribute to this guide or raise issues on GitHub if you get stuck!