Home Explore Help
Register Sign In
larva
/
disbot-a4
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: main
Branches Tags
disbot-a4
/
README.md

README.md 9.2 KB
Permalink History Raw

disbot-a4 — Simple, robust role selector bot

Author: Lari Natri, 2025

License: MIT

A simple, robust Discord role-picker bot built with py-cord and packaged for Docker Compose.

  • Language/Libs: Python 3.12, py-cord only
  • Persistence: SQLite (stdlib), bind-mounted ./data
  • Daily inactivity cleanup removes all pickable roles from users inactive for N days (default 14).
  • Auto-refresh updates all status panels and DM panels at a configurable interval (default 5 minutes).
  • Restart-safe: DB + tasks resume; re-create UI via /role-admin-post-status (or auto-post on startup if configured)
  • Public status panels: list pickable roles with member counts and "(inactive)/(full)" hints from configurable min/max values.
  • UI: Personal role picker via /roles (sent to your DMs) with buttons to toggle your roles.
  • UI: User slash commands for listing and toggling roles.
  • UI: Admin slash commands to configure pickable roles, limits, inactivity timeout, refresh cadence, list members, manage users, and post status panels.

1) Quick start

  1. Discord Developer Portal setup

Discord Developer Portal

  1. Create Application -> Bot: copy the token to secrets/discord_token.txt.
  2. Privileged Gateway Intents (Bot settings -> Privileged Gateway Intents):
    • Enable Server Members Intent
    • (Optional) Enable Message Content Intent if you want the bot to track activity from messages for inactivity cleanup. Otherwise the bot still works; you can set activity via role interactions only.
  3. Invite the bot with scopes:
    • bot, applications.commands
  4. Bot Permissions: at minimum grant
    • Manage Roles
    • View Channel
    • Send Messages
    • Read Message History
    • Manage Messages
  5. Copy the generated Invite URL and invite the bot to your server.
  6. Grab your Guild ID (enable Developer Mode in Discord client -> right-click server icon -> Copy Server ID) and set it in .env as GUILD_ID.

Role hierarchy: Move the bot's highest role above every pickable role you want it to manage. The bot cannot add/remove roles equal to or above its top role. Managed/integration roles cannot be assigned by bots.

  1. Create secrets & env

    mkdir -p secrets data
sudo chown -R 10001:10001 data
echo "YOUR_BOT_TOKEN_HERE" > secrets/discord_token.txt
cp .env.example .env
# Edit .env: set GUILD_ID and (optionally) ROLE_PANEL_CHANNEL_ID, etc.

  2. Build & run

    docker compose up -d --build --remove-orphans

  3. Add selectable roles for the server

    • On Discord server, add selectable roles with slash command: /role-admin-add-pickable:@Role (optional min_users, max_users)

    • See all commands with /role-help

  4. Post the role panel

    • If you set ROLE_PANEL_CHANNEL_ID in .env, the bot will auto-post the panel on startup.
    • Otherwise, in any channel, run (as an admin): /role-admin-post-status

2) Environment variables

Name Required Default Notes
GUILD_ID Yes — Guild (server) ID where the bot operates & registers commands (fast sync).
ROLE_PANEL_CHANNEL_ID No — If set, bot auto-posts the panel on startup to this channel.
INACTIVITY_DAYS_DEFAULT No 14 Initial value for inactivity (can be changed with slash command).
REFRESH_MINUTES_DEFAULT No '5' Initial value for refreshing role status on posts (can be changed with slash command).
DATABASE_PATH No /app/data/bot.db SQLite DB path (persisted via volume ./data:/app/data).
LOG_LEVEL No INFO DEBUG, INFO, WARNING, ERROR.
TZ No Europe/Helsinki Provided via Docker environment in docker-compose.yml.

Secret (via Docker secrets):

  • ./secrets/discord_token.txt — put your bot token here (no quotes, single line).

3) What the bot does

Public status panels

  • Posted with /role-admin-post-status (admin-only; posts a message visible to everyone).
  • Lists each pickable role, current member count, plus (inactive) if count < min and (full) if count ≥ max (when configured).
  • Contains a Refresh button.
  • The bot stores all posted panel message IDs and auto-refreshes them (see below).

Personal DM role picker

  • Users run /roles to receive a DM with a personalized panel.
  • Buttons show primary/secondary style depending on whether the user currently has each role.
  • If DMs are closed, the bot shows a one-off ephemeral panel in the channel instead (not tracked for auto-refresh).

Auto-refresh

  • Refresh cadence is configurable globally per guild via /role-admin-refresh (minutes).
  • The bot updates:
    • All public status panels it has posted in that guild.
    • All tracked DM panels it sent with /roles.
  • Also refreshes promptly after admin config changes and user role toggles.

Inactivity cleanup

  • Daily, removes all pickable roles from members whose last activity timestamp is older than N days (configurable).
  • "Activity" is updated on any message or role interaction handled by the bot.
  • Default inactivity days come from INACTIVITY_DAYS_DEFAULT and can be changed live using /role-admin-set-inactivity-days.

What counts as activity?

  • Any message a user sends in the guild updates their last_active timestamp.
  • The daily job removes selectable roles from users with no messages for longer than inactivity_days.

You can change inactivity_days anytime using /role-admin-set-inactivity-days. Default is taken from INACTIVITY_DAYS_DEFAULT when the bot first sees the guild.

4) Commands

User commands

  • /roles Open your personal role picker (DM). Shows the server name & ID in the message. > NOTE: The UI shows at most 25 role buttons in a single panel message > due to Discord limits.
  • /role-list List the pickable roles you currently have (ephemeral reply).
  • /role-pick <role> Add yourself to a pickable role.
  • /role-unpick <role> Remove yourself from a pickable role.
  • /role-toggle <role> Toggle a pickable role on/off.
  • /role-help Show all user commands. If you're an admin, admin commands are listed as well.

Admin commands

  • /role-admin-post-status Post a public role status panel in the current channel (anyone can see it). Panel lines include min/max-based labels: "(inactive)" if count < min and "(full)" if count ≥ max.
  • /role-admin-add-pickable <role> [min] [max] Add or update a pickable role and optional min/max hints.
  • /role-admin-remove-pickable <role> Remove a role from the pickable list.
  • /role-admin-set-role-limits <role> [min] [max] Adjust min/max hints for a pickable role.
  • /role-admin-set-inactivity-days <days> Set inactivity timeout in days (default: 14).
  • /role-admin-set-refresh-interval <minutes> Set auto-refresh interval in minutes (default: 5).
  • /role-admin-refresh-now Trigger an immediate refresh
  • /role-admin-list-users List all pickable roles and the users in each (ephemeral to the admin).
  • /role-admin-list-config Show current configuration (inactivity days, refresh minutes, pickable roles with limits).
  • /role-admin-add-user-for-role <user> <role> Add a specific user to a pickable role (admin-controlled).
  • /role-admin-remove-user-from-role <user> <role> Remove a specific user from a pickable role (admin-controlled).

All admin commands respond ephemerally to the invoking admin. Public status panels are visible to everyone.

5) Persistence

  • SQLite database at DATABASE_PATH (default /app/data/bot.db), bind-mounted to ./data/bot.db by docker-compose.
  • Tables:
    • settings (inactivity_days, refresh_minutes)
    • roles (pickable role IDs + optional min/max)
    • activity (last activity per user)
    • panels (public panel messages for auto-refresh)
    • dm_panels (user DM panels for auto-refresh)

Back up by copying the data/ directory (container must be stopped for consistent copy if heavy write load is ongoing).

6) Troubleshooting

  • Buttons say "I cannot manage that role due to role hierarchy/permissions."

    • Grant the bot Manage Roles permission.
    • Move the bot's highest role above all pickable roles.
    • Don't use managed/integration roles as pickables.

  • "Missing Access (50001)" when posting a status panel Verify the bot has View Channel and Send Messages in that channel. Avoid forum roots; use a text channel or a thread.

  • Commands don't show up If GUILD_ID is set, commands register immediately for that guild. Without it, global registration can take a while. Set GUILD_ID to your server ID in .env for instant registration during setup.

  • Inactivity cleanup appears to skip Ensure GUILD_ID is set to your target guild. The daily task only runs for GUILD_ID (by design).

  • DM panel not received User may have DMs closed. The bot will fallback with an ephemeral panel (not tracked for auto-refresh).