Skip to content
brandonbtm29Public

About

A friendly, self-hosted Discord bot for a friends' server: opt-in ping roles, movie nights (polls, ratings, history), birthdays, event reminders and more, with a swappable personality and failover across PCs.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Pingwin

Pingwin

CI License: MIT

A friendly, self-hosted Discord bot for a friends' server. It started with opt-in ping roles: members tap buttons in #roles to choose which pings they get (movie nights, streams, game days…), so the server can stop using @everyone for everything. It also has optional features you switch on when you want them: movie nights (watchlists, polls, ratings and a history), birthdays, event reminders, game day sign-ups, event attendance, stream alerts, welcome and approval, and a mod log.

  • Swappable personality: announcements and replies come from a persona file, so you can rename it or change its voice without touching code. The default, Pingwin, is a playful penguin: puns in announcements, plain words in mod tools and errors.
  • Runs on several PCs: one answers, the others wait on standby and take over if it goes offline.
  • Updates itself from GitHub.
  • Dashboard in your browser for settings, status and logs.

Getting started

📘 New to Pingwin? Follow the setup guide. It covers everything from creating the bot in Discord to posting your first menu, plus troubleshooting.

The short version, on a Windows PC that stays on:

  1. Create a bot in the Discord Developer Portal, copy its token, and invite it with https://discord.com/oauth2/authorize?client_id=APP_ID&scope=bot+applications.commands&permissions=2815033570708480.
  2. Install Python 3.11+ and Git, then git clone https://github.com/brandonbtm29/Pingwin.git.
  3. Double-click scripts\setup.cmd and paste your token when asked.
  4. Double-click scripts\run_pingwin.cmd, then scripts\open_dashboard.cmd, and follow the Setup tab's checklist.
  5. Optional: scripts\install_autostart.cmd starts Pingwin in the background (no window) when you sign in, and adds a Pingwin Dashboard shortcut to your desktop. Stop it with Status → Stop Pingwin.
  6. Optional: to let people rate movies by voice message, also run .venv\Scripts\python -m pip install -e ".[voice]" in the Pingwin folder (on every PC that may answer). See Rate by voice.

Commands

Every command lives under /pingwin, so it doesn't get mixed up with other bots' commands.

Command Who What
/pingwin rolemenu setup Manage Roles Creates missing menu roles (pingable, no permissions) and checks the rest
/pingwin rolemenu check Manage Roles Same report, changes nothing
/pingwin rolemenu post [channel] [menu] Manage Roles Posts a button menu (the ping menu, or another one like time zones)
/pingwin rolemenu refresh Manage Roles Updates posted menus in place after you change the roles
/pingwin timezone set · show · remove Everyone Pick your time zone, so times you type mean your time
/pingwin about Everyone Says hi
/pingwin status Everyone Which PC is answering, version, uptime
/pingwin dashboard Manage Server (or the dashboard admin role) Links to the dashboard (when it's online)
/pingwin reload Manage Server Reload settings now (they also reload on their own within a minute)
/pingwin restart Manage Server Restart and install any update from GitHub

Only members with the Friend role can use the menus (required_role in config.toml). Besides the ping menu you can add more menus, each its own message, such as a time zone menu where picking a role also sets that person's time zone. A menu can let people pick any number of roles, or just one.

Features

Eight optional features, all off until you switch them on in the dashboard's Features tab. How to set them up

Feature Commands What it does
Event reminders (automatic) Pings the roles whose keywords match a new Discord Event, reminds before it starts, and keeps repeating events at their local time when the clocks change
Birthdays /pingwin birthday set · remove · upcoming (mods: set_for · remove_for · add_other · remove_other) A shout-out on the day; optional birthday role; a ⭐ Star birthdays message for people without Discord
Movie night /pingwin movie nominate · list · remove · poll · endpoll · watched · tonight · history · rate · page · queue · franchise · skip · unskip Watchlists, Discord or ranked-choice polls, franchise queues, weeks off, a "did it happen?" card for the movie mods, a Rate it button (typed or by voice message) with a question game, and movie pages (history, ratings, stats)
Game day sign-ups /pingwin gameday create · cancel "Who's in?" buttons and a reminder to everyone who's in
Event attendance /pingwin attendance add · remove · code · history Takes attendance at Discord Events (voice or an "I'm here" button) and pays a reward into UnbelievaBoat
Stream alerts (automatic) Posts once when a streamer goes live on Twitch, YouTube or Discord (Go Live)
Welcome and approval (buttons) Welcomes new members; mods click Approve to give them Friend
Mod log (automatic) Joins, leaves, bans, role changes and deleted messages (edits too, if you want), in a private channel

Admins decide how movie night works: who can nominate, who can start polls, where polls go, how the poll's movies are picked, how long it runs, and what happens on a tie. Welcome and the mod log need privileged intents (details).

Dashboard

Double-click the Pingwin Dashboard desktop shortcut (or scripts\open_dashboard.cmd; make the shortcut with scripts\create_shortcuts.cmd). It starts Pingwin in the background if needed, and opens a page in your browser with six tabs:

  • Status: which PC is answering, Discord connection, version; reload, restart, check for updates, stop; remote access
  • Role menu: several menus (pings, time zones, ...); add, remove and reorder roles, set emoji and descriptions, choose who can use them, see which roles are ready, create missing ones, and post menus
  • Features: switch on and set up the optional features, plus event attendance, the birthday list and the movie watchlists
  • PCs & failover: turn failover on, pick the status channel, order the PCs, add a backup PC
  • Setup: a checklist of what's done and what's left, a check that Pingwin can reach every channel and role it's been given, and an About page
  • Logs: this PC's recent log, live

Long pages have an On this page list in the empty space on the left (a ☰ Sections button on smaller screens) to jump to any section, with Expand all and Collapse all. Every section folds up with the ▾ next to its title, and each browser remembers what you folded. The movie pages work the same way.

Every PC running Pingwin has its own dashboard. Changes save to the shared config.toml, so they reach every PC. The page only answers on that PC (127.0.0.1:8787; change it under [dashboard]), and open_dashboard.cmd signs you in with a key kept in the project folder.

Co-admins can use it from anywhere too: put it online with Tailscale Funnel and they sign in with Discord (Manage Server or a role you pick), with nothing to install. Members (with the Friend role) can sign in there too, but only get the movie pages. Remote dashboard and co-admins. When several people have it open, it shows who's where, stops a save that would overwrite someone's newer change, and helps sort out SyncThing conflicts.

Where settings live

Where What Synced?
Settings folder (e.g. SyncThing\Pingwin) config.toml, secrets.env (token and API keys), personas\, menus.json, and state\ (what the features keep: birthdays, watchlists, the movie library, ...) Yes: same on every PC
Project folder .env PINGWIN_DATA (path to the settings folder), PINGWIN_NODE (this PC's name) No: one per PC
Project folder logs\, .dashboard-key, .dashboard-sessions.json, models\ Log, dashboard sign-in key, Discord sign-ins, the speech-to-text model (if voice ratings are installed) No
GitHub The code Pulled by every PC

Running on more than one PC (failover)

Every PC connects to Discord, but only one answers at a time. The active PC checks in every 30 s by editing a status message in a mod-only channel. If check-ins stop for 2 minutes, the next PC in the list takes over. When a PC higher in the list comes back, it takes the job back as soon as SyncThing has brought its copy of the shared folder up to date.

  1. Make a mod-only channel such as #pingwin-status, and let Pingwin view and post in it.
  2. In config.toml, list the PCs in order of preference:
    [failover]
    enabled = true
    status_channel_id = 123456789012345678
    pcs = ["MAIN-PC", "FRIENDS-PC"]   # 1st choice, then backups in order
    To add another PC later, add its name to the end of the list. A PC that isn't listed still helps, but only when every listed PC is offline.
  3. Add each backup PC with Add a backup PC on the same tab: send your friend the invite message, and paste back the reply code their installer shows. Adding a backup PC
  4. Share the SyncThing settings folder with that PC.

A backup only helps with internet outages if it's on a different network (e.g. a friend's house). Anyone running a backup has the bot token, so only use PCs you trust.

Updating

  • Code: push to GitHub. Every PC checks every 30 minutes ([updates] check_minutes), restarts, pulls, and reinstalls. For an immediate update on the active PC, run /pingwin restart. PCs with uncommitted code changes skip auto-updates, and a PC only installs commits signed with a key in .github/allowed_signers (see Signing commits); the Status tab says when it's holding one back.
  • Settings: edit config.toml or a persona on one PC. SyncThing copies it, and every Pingwin reloads it within a minute. After changing the menu, click Update posted menus (or /pingwin rolemenu refresh).
  • Personality: copy personas\pingwin.toml into the settings folder's personas\, rename it (e.g. pirate.toml), rewrite the lines, and set persona = "pirate".

See CHANGELOG.md for what changed in each version.

Development

See CONTRIBUTING.md. In short:

.venv\Scripts\activate
pre-commit install   # once: blocks secrets and lints each commit
pytest

Each feature lives in src/pingwin/cogs/ as its own module. Anything that runs on a timer (reminders, polls) must check bot.is_active so standby PCs stay quiet.

Roadmap

  • Movie-night polls, event reminders, game day sign-ups, stream alerts (0.7.0)
  • Birthdays, welcome and approval, mod log (0.7.0)
  • Persona switching from Discord
  • AI personality (much later)

Privacy

With the default features, Pingwin can't read messages and has no tracking. It keeps a small activity log (who opted into which role) on the PC that runs it. The mod log, if you turn it on, can read messages so it can record deletes (and edits, if you want). Movie night's voice ratings only listen to voice messages sent to Pingwin, turn them into text on that PC, and don't keep the recording. See the privacy notice.

License

MIT

About

A friendly, self-hosted Discord bot for a friends' server: opt-in ping roles, movie nights (polls, ratings, history), birthdays, event reminders and more, with a swappable personality and failover across PCs.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages