MagnoliaBot is a Node/TypeScript Discord bot backed by MongoDB, deployed as a Docker container. This section is for developers who want to run their own instance — most people should just invite the hosted bot instead.
README. Ask for access if you'd like to self-host.Prerequisites
- A Discord application + bot token (from the Discord Developer Portal)
- Docker on the host (a small VPS is plenty)
- MongoDB 8 (run as a container alongside the bot)
- Optional: a Google Gemini API key to enable AI replies
Run it locally
npm install npm run dev # dev mode, auto-restarts on changes # or, a production build: npm run build npm start
Environment variables
Copy .env.development and fill in your values, or set these directly:
| Variable | Required | Description |
|---|---|---|
TOKEN | Yes | Discord bot token |
CLIENT_ID | Yes | Discord application client ID |
OWNER_ID | Yes | Discord user ID of the bot owner — the root Super Admin, who can appoint others and can never be removed |
MONGODB_URI | Yes | MongoDB connection string (e.g. mongodb://mongodb:27017/magnoliabot) |
GEMINI_API_KEY | No | Google Gemini key — enables AI features |
GEMINI_MODEL | No | Gemini model to use (default: gemini-2.5-flash-lite) |
AI_DISABLED | No | Global kill switch — set to any non-empty value to silence AI replies everywhere |
AI_DAILY_REPLY_CAP | No | Max AI replies per server per UTC day (default: 50) |
Slash commands register globally — the bot works in any server it's invited to, and the watcher posts to each subscription's channel rather than one configured channel. Discord can take up to an hour to propagate newly-registered commands.
MongoDB container
docker network create magnolia-net docker volume create mongodb-data docker run -d --name mongodb --restart unless-stopped \ --network magnolia-net \ -v mongodb-data:/data/db \ mongo:8
Deployment
The reference deployment runs on a VPS via GitHub Actions: every push to main builds a fresh Docker image, stops the old container, and starts a new one on the magnolia-net network alongside MongoDB. The container runs with --restart unless-stopped, so it recovers on reboot.
Handy post-deploy commands:
docker logs magnolia-bot -f # stream logs docker ps # check container status docker restart magnolia-bot # restart docker exec -it magnolia-bot /bin/sh # shell into the container
database/README.md.