Stat Bot

Discord bot for Hackerspace server statistics.

It collects activity from Discord events, stores daily aggregates in MongoDB, and keeps one public stats message updated in the configured channel.

It tracks:

• total messages
• reactions given and received
• active users per day
• rolling stats for 24h, 7d, and 30d

The bot does not backfill old Discord messages. Statistics start from the moment the bot is running.

Production Deploy

Deployment is handled by GitHub Actions in .github/workflows/publish.yml.

On push to main, or manual workflow dispatch:

1. GitHub Actions builds the Docker image.
2. The image is pushed to ghcr.io/nu31hackerspace/stat-bot.
3. docker-stack.yml is deployed to the server over SSH.
4. The service runs as stat-bot_app in Docker Swarm.
5. MongoDB is expected to be external and reachable through MONGO_URI.

GitHub Secrets

Required secrets:

Name	Description
DISCORD_TOKEN	Discord bot token
MONGO_URI	Full MongoDB connection URI
ROOT_SSH_PRIVATE_KEY	SSH private key for Docker Stack deploy

GitHub Variables

Required variables:

Name	Description
HOST	Deploy server host/IP
USERNAME	SSH user for deploy
STATS_CHANNEL_ID	Discord channel ID where the stats message is posted

Optional variables:

Name	Default	Description
MONGO_DB	stat_database	Mongo database name
GUILD_ID	empty	Restrict bot to one Discord guild and sync slash commands there
MONGO_USERS_COLLECTION	users	User stats collection
MONGO_SERVERS_COLLECTION	servers	Server stats collection
MONGO_META_COLLECTION	meta	Metadata collection
LOG_LEVEL	INFO	Python log level
LOG_FILE	logs/stat_bot.log	Log file path inside the container

Runtime Permissions

The Discord bot needs access to the stats channel and these permissions:

• View Channel
• Send Messages
• Embed Links
• Read Message History
• Manage Messages, if it must edit/recreate the stats message reliably

Local Run

Create .env from .env.example, then run:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m bot.main

For local Docker bot-only mode:

docker compose up --build

For local Docker with bundled MongoDB:

docker compose -f docker-compose.yml -f docker-compose.mongo.yml up --build