Prerequisites
Before you begin, ensure you have:- Docker and Docker Compose installed
- A Discord account with server administrator permissions
- A PostgreSQL 13 database (or use the Docker Compose setup below)
- An SMTP email server for student verification (e.g., Gmail, institutional email)
- A student email domain for verification (e.g.,
@stud.hs-kempten.de)
Faculty Bot is written in Rust and uses the Poise framework for Discord interactions. It features student verification, XP/leveling systems, RSS feeds, meal plan posting, and more.
Step 1: Create a Discord Application
Create the Application
- Go to the Discord Developer Portal
- Click New Application
- Name it “Faculty Bot” (or your preferred name)
- Click Create
Create a Bot User
- Navigate to the Bot section in the left sidebar
- Click Add Bot and confirm
- Under the Token section, click Reset Token and copy it
- Save this token securely - you’ll need it for the
.envfile
Configure Bot Permissions
Enable these Privileged Gateway Intents:
- Server Members Intent
- Message Content Intent
- Presence Intent
Invite the Bot to Your Server
- Go to the OAuth2 → URL Generator section
- Select these scopes:
botapplications.commands
- Select these bot permissions:
- Manage Roles
- Manage Channels
- Send Messages
- Manage Messages
- Embed Links
- Attach Files
- Read Message History
- Add Reactions
- Use Slash Commands
- Copy the generated URL and open it in your browser
- Select your server and authorize the bot
Step 2: Set Up Your Discord Server
Faculty Bot requires specific channels and roles to function. Create these in your Discord server:Required Roles
staffrole
Management role for bot administration. Members with this role can edit bot settings via commands.
verified
Assigned to users after email verification. Use this to control channel access.
semestermodrole
Semester moderator role for student representatives.
mealplannotify
Receives notifications when new meal plans are posted.
Required Channels
Create these channels and note their IDs (Right-click → Copy ID):- #logs - Bot activity logs (staff only)
- #news - Bot announcements
- #xp - Level-up notifications
- #rules - Server rules
- #ads - External ads (auto-deleted after timeout)
- #mealplan - Meal plan updates
- 🔊 New VoiceChannel - Voice channel for dynamic channel creation
Enable Developer Mode in Discord (Settings → Advanced → Developer Mode) to copy channel and role IDs.
Step 3: Configure Environment Variables
Create a.env file in your project directory:
.env
Email Configuration
- Gmail
- Institutional Email
Step 4: Configure Bot Settings
Create aconfig.json file with your Discord IDs and settings:
config.json
Configuration Options Explained
Configuration Options Explained
- prefix: Command prefix for text commands (e.g.,
>help) - charsForLevel: Number of characters needed to gain 1 XP (default: 25)
- xpScalingFactor: XP scaling multiplier for leveling (default: 0.5)
- adstimeout: Time in milliseconds before ads are deleted (default: max int for no deletion)
- postMealplan: Enable/disable automatic meal plan posting
- mealplan.check: Minutes between meal plan update checks
- mealplan.postOnDay: Day of week to post meal plans (Monday-Sunday)
- mealplan.postAtHour: Time to post meal plans (format: HH:MM:SS)
Step 5: Deploy with Docker Compose
Create adocker-compose.yml file:
docker-compose.yml
You’ll need the
migrations/faculty_manager.sql file from the repository. Download it or clone the repo to get the database schema.Step 6: Download Database Schema
Download the database initialization script:migrations/faculty_manager.sql
Step 7: Launch Faculty Bot
Start the bot with Docker Compose:Your bot should now be online in your Discord server! Check the bot’s status in your member list.
Step 8: Test the Bot
Run the register command in Discord to ensure slash commands are working:The
>register command requires the Manage Server permission and registers all slash commands for your server.Verification Workflow
Here’s how student verification works:Student Initiates Verification
User runs:
/verify init email:[email protected]Bot Sends Verification Email
The bot sends a verification code to the student’s email address using your SMTP server.
Student Enters Code
User runs:
/verify code:123456The bot checks the code and assigns the verified role if correct.Troubleshooting
Bot is offline
Bot is offline
Check the container logs:Common issues:
- Invalid Discord token
- Database connection failed
- Missing environment variables
Email verification not working
Email verification not working
Verify your SMTP settings:Check:
- SMTP credentials are correct
- SMTP_PORT is correct (usually 587 for TLS)
- Firewall isn’t blocking outbound SMTP
- Using app passwords for Gmail
Slash commands not appearing
Slash commands not appearing
- Ensure the bot has
applications.commandsscope - Run
>registerwith Manage Server permission - Wait up to 1 hour for Discord to propagate commands globally
- Try kicking and re-inviting the bot with the correct scopes
Database connection errors
Database connection errors
Check that the database container is running:Verify DATABASE_URL in
.env matches your Docker service name:Next Steps
Configure Features
Set up meal plans, RSS feeds, and advanced features
Commands Reference
View all available bot commands
Administration
Learn about staff and moderation commands
Development
Contribute to Faculty Bot or build from source