Self-Hosting

Overlap Bot is fully open source (MIT) and designed to run on your own infrastructure.

Prerequisites

Python 3.10+
A Discord application with a bot token — Discord Developer Portal
(Optional) A Stripe account for premium subscription handling

Installation

1. Clone the repository

git clone https://github.com/smithlabs/overlap-bot.git
cd overlap-bot

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Copy the example env file and fill in your values:

cp .env.example .env

Required:

DISCORD_TOKEN=your_discord_bot_token_here

Optional bot settings:

# Guild ID for instant dev command sync (skip global 1-hour propagation)
DEV_GUILD_ID=123456789012345678

# SQLite database directory (default: ./data)
DATA_DIR=./data

# Log verbosity: DEBUG | INFO | WARNING | ERROR
LOG_LEVEL=INFO

# Runtime environment
ENV=production

# Event limits (overrides defaults)
FREE_TIER_MAX_EVENTS=5
PREMIUM_TIER_MAX_EVENTS=999

4. Configure Stripe (optional)

Only required if you want to offer premium subscriptions. Skip this section if you’re self-hosting for personal use.

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_MONTHLY=price_...
STRIPE_PRICE_YEARLY=price_...
WEB_BASE_URL=https://yourdomain.com
WEB_HOST=0.0.0.0
WEB_PORT=8080
STRIPE_SUCCESS_URL=https://yourdomain.com/payment/success
STRIPE_CANCEL_URL=https://yourdomain.com/payment/cancel

In your Stripe dashboard, configure a webhook pointing to https://yourdomain.com/webhooks/stripe and enable these events:

checkout.session.completed
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_succeeded
invoice.payment_failed

5. Run the bot

python bot.py

To also run the Stripe webhook server (only needed for payments):

python -m web.server

6. Invite the bot to your server

In the Discord Developer Portal:

Go to your application → OAuth2 → URL Generator
Select scopes: bot, applications.commands
Select permissions: Send Messages, Embed Links, Attach Files, Use Slash Commands, Create Public Threads, Send Messages in Threads, Manage Threads, Read Message History
Copy the generated URL and open it in a browser to authorize

Running as a service

systemd (Linux)

Create /etc/systemd/system/overlap-bot.service:

[Unit]
Description=Overlap Bot
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/overlap-bot
ExecStart=/usr/bin/python3 bot.py
Restart=always
RestartSec=5
EnvironmentFile=/opt/overlap-bot/.env
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable overlap-bot
sudo systemctl start overlap-bot
sudo journalctl -u overlap-bot -f

Process manager (PM2)

npm install -g pm2
pm2 start bot.py --name overlap-bot --interpreter python3
pm2 save
pm2 startup

Database

The bot uses SQLite with WAL mode at data/eventbot.db (or $DATA_DIR/eventbot.db).

The schema is created automatically on first run
Migrations apply automatically on startup — no manual steps needed
Back up the .db file periodically; all data lives there

Upgrading

git pull
pip install -r requirements.txt
# Restart the bot — migrations run on startup

Next: Configuration Reference →