Installation - Faculty Bot

Faculty Bot can be installed using three different methods depending on your requirements and infrastructure. This guide covers all installation options from easiest to most advanced.

Installation Methods

Docker

Recommended: Easiest setup with automated database management

Scripts

Automated scripts for Linux and Windows with process management

Manual

Full control with manual compilation and configuration

Prerequisites

Common Requirements (All Methods)

A Discord account with server administrator permissions
Discord bot application and token (Setup Guide)
SMTP email server credentials for student verification
Server or machine to host the bot (Linux, Windows, or macOS)

Method-Specific Requirements

Docker
Scripts
Manual

Docker 20.10+
Docker Compose 2.0+
1 GB RAM minimum, 2 GB recommended
5 GB disk space

Method 1: Docker (Recommended)

The easiest and most reliable installation method using Docker and Docker Compose.

Step 1: Install Docker

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify installation
docker --version
docker compose version

Step 2: Prepare Configuration Files

Create a new directory for Faculty Bot:

mkdir faculty-bot
cd faculty-bot
mkdir migrations images

Step 3: Create Environment File

Create a .env file:

.env

DISCORD_TOKEN=your_discord_bot_token_here

# Database configuration
DATABASE_URL=postgres://faculty_manager:averysecurepasswordyes@database:5432/faculty_manager

# Command prefix
PREFIX=>

# Email configuration
SEND_FROM_ADDRESS=noreply@youruniversity.edu
MAIL_USERNAME=your_email@youruniversity.edu
MAIL_PASSWORD=your_email_password_or_app_password
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587

# PostgreSQL credentials
POSTGRES_USER=faculty_manager
POSTGRES_PASSWORD=averysecurepasswordyes
POSTGRES_DB=faculty_manager

# Logging configuration
RUST_LOG="info,sqlx=error,sqlx::query=error,sqlx::query_as=error"

# Optional: InfluxDB metrics (leave empty if not using)
INFLUX_TOKEN=

Replace your_discord_bot_token_here with your actual Discord bot token from the Discord Developer Portal.

Step 4: Create Configuration File

Create a config.json file with your Discord server IDs:

config.json

{
  "prefix": ">",
  "channels": {
    "xp": "YOUR_XP_CHANNEL_ID",
    "rules": "YOUR_RULES_CHANNEL_ID",
    "news": "YOUR_NEWS_CHANNEL_ID",
    "logs": "YOUR_LOGS_CHANNEL_ID",
    "ads": "YOUR_ADS_CHANNEL_ID",
    "createChannel": "🔊 New VoiceChannel",
    "mealplan": "YOUR_MEALPLAN_CHANNEL_ID"
  },
  "colors": {
    "blue": "#4200ff",
    "lightblue": "#FFFFF",
    "green": "#28823d",
    "red": "#cf0a0a"
  },
  "roles": {
    "staffrole": "YOUR_STAFF_ROLE_ID",
    "semestermodrole": "YOUR_SEMESTER_MOD_ROLE_ID",
    "verified": "YOUR_VERIFIED_ROLE_ID",
    "mealplannotify": "YOUR_MEALPLAN_NOTIFY_ROLE_ID"
  },
  "general": {
    "adstimeout": 2147483647,
    "charsForLevel": 25,
    "xpScalingFactor": 0.5
  },
  "mealplan": {
    "postMealplan": false,
    "url": "http://www.max-manager.de/daten-extern/augsburg/pdf/wochenplaene/hs-kempten/aktuell.pdf",
    "check": 30,
    "postOnDay": "Monday",
    "postAtHour": "09:00:00",
    "imgsettings": {
      "density": 400,
      "quality": 100,
      "flatten": false,
      "width": 768,
      "height": 512
    }
  },
  "rssSettings": {
    "postRss": false,
    "rssFeedData": {},
    "rssCheckIntervalHours": 1,
    "rssCheckAfterTimeHours": 8
  },
  "podcastSettings": {
    "postPodcast": false,
    "podcastCheckInterval": 1,
    "podcastUrl": "",
    "podcastChannel": ""
  }
}

Enable Developer Mode in Discord (Settings → Advanced → Developer Mode) to copy channel and role IDs by right-clicking them.

Step 5: Download Database Schema

Download the database initialization SQL file:

curl -o migrations/faculty_manager.sql https://raw.githubusercontent.com/rndrmu/FacultyManager/main/migrations/faculty_manager.sql

Or clone the entire repository:

git clone https://github.com/rndrmu/FacultyManager.git
cp FacultyManager/migrations/faculty_manager.sql migrations/

Step 6: Create Docker Compose File

Create a docker-compose.yml file:

docker-compose.yml

version: "3"
services:
  bot:
    container_name: faculty_manager
    image: ghcr.io/rndrmu/facultymanager:latest
    volumes:
      - './config.json:/config.json:ro'
      - './images:/images'
      - './migrations:/migrations'
    env_file:
      - .env
    depends_on:
      - database
    networks:
      - bot
    restart: unless-stopped

  database:
    container_name: faculty_manager_db
    image: postgres:13
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - ./migrations/faculty_manager.sql:/docker-entrypoint-initdb.d/init.sql
      - postgres_data:/var/lib/postgresql/data
    networks:
      - bot
    restart: unless-stopped

volumes:
  postgres_data:

networks:
  bot: {}

Build from source instead of using pre-built image

If you want to build the Docker image yourself, replace the image line with:

build: .

And place the complete Faculty Bot source code in the same directory. Then run:

docker compose build
docker compose up -d

Step 7: Launch Faculty Bot

Start the bot using Docker Compose:

docker compose up -d

Monitor the logs to verify successful startup:

docker compose logs -f bot

Expected output:

Loaded .env file
Starting up
Mealplan will be posted on Monday at 09:00:00
Starting email task
Successfully registered Application Commands globally

Your Faculty Bot should now be online in Discord!

Docker Management Commands

# Stop the bot
docker compose down

# Restart services
docker compose restart

# View logs
docker compose logs -f bot

# Update to latest version
docker compose pull
docker compose up -d

# Access database directly
docker compose exec database psql -U faculty_manager -d faculty_manager

# Backup database
docker compose exec database pg_dump -U faculty_manager faculty_manager > backup.sql

# Remove all containers and volumes (DESTRUCTIVE)
docker compose down -v

Method 2: Automated Scripts

Use the provided launch scripts for a semi-automated installation with process management.

Linux Installation

Clone the Repository

git clone https://github.com/rndrmu/FacultyManager.git
cd FacultyManager

Install Rust Toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustc --version

Install PostgreSQL

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Initialize Database

# Create database user and database
sudo -u postgres psql << EOF
CREATE USER faculty_manager WITH PASSWORD 'averysecurepasswordyes';
CREATE DATABASE faculty_manager OWNER faculty_manager;
\q
EOF

# Initialize schema
psql -U faculty_manager -d faculty_manager -f migrations/faculty_manager.sql

Configure Environment

Create a .env file (see Docker method for template) and config.json:

cp .env.example .env
nano .env  # Edit with your credentials
nano config.json  # Add your Discord IDs

Build the Bot

cargo build --release

Rust compilation can take 10-30 minutes and use significant CPU and RAM. This is normal due to Rust’s compile-time safety checks.

Launch with Process Manager

Choose your init system:

systemd
OpenRC
Docker

# Install service
sudo cp faculty_manager.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable faculty_manager
sudo systemctl start faculty_manager

# Check status
sudo systemctl status faculty_manager

# View logs
sudo journalctl -u faculty_manager -f

Or use the launch script:

./launch_bot.sh systemd

# Install service
sudo cp faculty_manager.service /etc/init.d/faculty-manager
sudo rc-update add faculty-manager
sudo rc-service faculty-manager start

# Check status
sudo rc-service faculty-manager status

Or use the launch script:

./launch_bot.sh openrc

Use the script to pull and run the pre-built Docker image:

./launch_bot.sh docker

This will:

Remove old containers
Pull latest image from GitHub Container Registry
Start database container
Start bot container

Windows Installation

Install Prerequisites

Download and install:

Clone Repository

Open PowerShell:

git clone https://github.com/rndrmu/FacultyManager.git
cd FacultyManager

Initialize Database

Open SQL Shell (psql) and run:

CREATE USER faculty_manager WITH PASSWORD 'averysecurepasswordyes';
CREATE DATABASE faculty_manager OWNER faculty_manager;
\c faculty_manager
\i C:/path/to/FacultyManager/migrations/faculty_manager.sql

Configure Files

Create .env and edit config.json with your Discord IDs (see Docker method for templates).

Build and Run

Option 1: Use the PowerShell script

.\launch_windows.ps1

Option 2: Manual build and run

cargo build --release
.\target\release\faculty_manager.exe

Run as Windows Service (Optional)

Use NSSM to run as a service:

# Install NSSM
choco install nssm

# Create service
nssm install FacultyBot "C:\path\to\FacultyManager\target\release\faculty_manager.exe"
nssm set FacultyBot AppDirectory "C:\path\to\FacultyManager"
nssm start FacultyBot

Method 3: Manual Installation

For advanced users who want full control over the installation process.

Step 1: Install Rust Toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Select the stable toolchain when prompted. Verify installation:

rustc --version
cargo --version

Step 2: Install System Dependencies

sudo apt-get update
sudo apt-get install -y \
    postgresql-13 \
    imagemagick \
    graphicsmagick \
    ghostscript \
    pkg-config \
    libssl-dev \
    cmake \
    git

Step 3: Clone and Build

# Clone repository
git clone https://github.com/rndrmu/FacultyManager.git
cd FacultyManager

# Build release binary
cargo build --release

The compiled binary will be at target/release/faculty_manager.

First-time compilation typically takes 15-30 minutes depending on your system. Rust performs extensive compile-time checks for memory safety and correctness.

Step 4: Set Up PostgreSQL

# Start PostgreSQL
sudo systemctl start postgresql

# Create user and database
sudo -u postgres psql << EOF
CREATE USER faculty_manager WITH PASSWORD 'your_secure_password';
CREATE DATABASE faculty_manager OWNER faculty_manager;
GRANT ALL PRIVILEGES ON DATABASE faculty_manager TO faculty_manager;
\q
EOF

# Initialize database schema
psql -U faculty_manager -d faculty_manager -f migrations/faculty_manager.sql

Step 5: Configure Environment

Create .env file:

DISCORD_TOKEN=your_discord_token
DATABASE_URL=postgres://faculty_manager:your_secure_password@localhost:5432/faculty_manager
PREFIX=>
SEND_FROM_ADDRESS=noreply@youruniversity.edu
MAIL_USERNAME=your_email
MAIL_PASSWORD=your_password
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
RUST_LOG="info,sqlx=error,sqlx::query=error,sqlx::query_as=error"

Edit config.json with your Discord server IDs (see Docker method for full template).

Step 6: Run Faculty Bot

# Direct execution
./target/release/faculty_manager

# Or with nohup for background execution
nohup ./target/release/faculty_manager > bot.log 2>&1 &

Step 7: Set Up Process Manager

systemd
PM2
screen

Edit faculty_manager.service with your paths:

faculty_manager.service

[Unit]
Description=Faculty Manager Discord Bot
After=network.target postgresql.service

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/FacultyManager
ExecStart=/path/to/FacultyManager/target/release/faculty_manager
Restart=always
RestartSec=10
Environment="RUST_LOG=info,sqlx=error"

[Install]
WantedBy=multi-user.target

Install and start:

sudo cp faculty_manager.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable faculty_manager
sudo systemctl start faculty_manager

Install PM2:

npm install -g pm2

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'faculty-bot',
    script: './target/release/faculty_manager',
    cwd: '/path/to/FacultyManager',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      RUST_LOG: 'info,sqlx=error'
    }
  }]
};

Start with PM2:

pm2 start ecosystem.config.js
pm2 save
pm2 startup

Simple screen session (not recommended for production):

screen -S faculty-bot
./target/release/faculty_manager
# Press Ctrl+A then D to detach

# Reattach with:
screen -r faculty-bot

Post-Installation Steps

After installation with any method:

1. Register Slash Commands

In your Discord server, run:

>register

You need the Manage Server permission to run this command. It registers all slash commands globally.

2. Configure ImageMagick (For Meal Plans)

If using meal plan functionality, disable PDF restrictions:

# Linux
sudo mv /etc/ImageMagick-6/policy.xml /etc/ImageMagick-6/policy.xml.off

# Or edit the file and comment out PDF restrictions
sudo nano /etc/ImageMagick-6/policy.xml
# Comment out the line: <policy domain="coder" rights="none" pattern="PDF" />

3. Test Verification System

Test the email verification:

/verify init email:test@stud.hs-kempten.de

Check bot logs for email sending status.

4. Configure Channel Permissions

Set up channel permissions so only users with the verified role can access certain channels:

Go to channel settings → Permissions
Deny @everyone from viewing the channel
Allow @verified role to view and send messages

Updating Faculty Bot

Docker
Manual/Scripts

docker compose pull
docker compose up -d

cd FacultyManager
git pull origin main
cargo build --release
sudo systemctl restart faculty_manager

Troubleshooting

Compilation Errors

Common Rust compilation issues:Error: failed to run custom build command for openssl-sys

# Install OpenSSL development libraries
sudo apt-get install libssl-dev pkg-config

Error: linker 'cc' not found

# Install build essentials
sudo apt-get install build-essential

Error: failed to run custom build command for sqlx-macros

# Ensure DATABASE_URL is set during compilation
export DATABASE_URL=postgres://faculty_manager:password@localhost/faculty_manager
cargo clean
cargo build --release

Database Connection Issues

Error: connection refusedCheck PostgreSQL is running:

sudo systemctl status postgresql
sudo systemctl start postgresql

Error: authentication failedUpdate PostgreSQL authentication:

sudo nano /etc/postgresql/13/main/pg_hba.conf
# Change 'peer' to 'md5' for local connections
# Restart PostgreSQL
sudo systemctl restart postgresql

Test database connection:

psql -U faculty_manager -d faculty_manager -h localhost

Permission Errors

Bot can’t assign roles:Ensure the bot’s role is above the roles it needs to assign in the Discord role hierarchy.Bot can’t send messages in channels:Check channel permissions and ensure the bot has:

View Channel
Send Messages
Embed Links
Attach Files

Email Sending Failures

Enable debug logging:

RUST_LOG="debug" ./target/release/faculty_manager

Common issues:

Gmail: Enable “Less secure app access” or use App Passwords
Port blocked: Ensure port 587 (or 465) isn’t blocked by firewall
Invalid credentials: Verify MAIL_USERNAME and MAIL_PASSWORD

Test SMTP connection:

telnet smtp.gmail.com 587

High Memory Usage

Faculty Bot uses approximately 50-150 MB of RAM normally.If memory usage is high:

Check for memory leaks in logs
Restart the bot
Reduce database connection pool size in source code
Disable unnecessary features (meal plans, RSS, podcasts)

Security Best Practices

Environment Variables

Never commit .env files
Use strong database passwords
Rotate credentials regularly
Use app passwords for email

File Permissions

chmod 600 .env
chmod 640 config.json
chown botuser:botuser .env config.json

Network Security

Run database on localhost only
Use firewall rules
Don’t expose PostgreSQL port externally
Use TLS for SMTP

Updates

Keep Rust toolchain updated
Update dependencies regularly
Monitor security advisories
Update Docker images weekly

Next Steps

Quickstart Guide

Quick setup guide for Docker deployment

Configuration

Configure meal plans, RSS feeds, and features

Commands

Learn all available bot commands

Development

Contribute to Faculty Bot

Deployment

Deploy to production

Web Interface

Web dashboard and API

Getting Help

If you encounter issues:

Check the GitHub Issues
Review bot logs for error messages
Join the Discord community (if available)
Open a new issue with:
- Installation method used
- Operating system and version
- Complete error messages
- Relevant log output

Faculty Bot is open source and actively maintained. Contributions and feedback are welcome!

Get Started

Configuration

Features

Deployment

​Installation Methods

Docker

Scripts

Manual

​Prerequisites

​Common Requirements (All Methods)

​Method-Specific Requirements

​Method 1: Docker (Recommended)

​Step 1: Install Docker

​Step 2: Prepare Configuration Files

​Step 3: Create Environment File

​Step 4: Create Configuration File

​Step 5: Download Database Schema

​Step 6: Create Docker Compose File

​Step 7: Launch Faculty Bot

​Docker Management Commands

​Method 2: Automated Scripts

​Linux Installation

​Windows Installation

​Method 3: Manual Installation

​Step 1: Install Rust Toolchain

​Step 2: Install System Dependencies

​Step 3: Clone and Build

​Step 4: Set Up PostgreSQL

​Step 5: Configure Environment

​Step 6: Run Faculty Bot

​Step 7: Set Up Process Manager

​Post-Installation Steps

​1. Register Slash Commands

​2. Configure ImageMagick (For Meal Plans)

​3. Test Verification System

​4. Configure Channel Permissions

​Updating Faculty Bot

​Troubleshooting

​Security Best Practices

Environment Variables

File Permissions

Network Security

Updates

​Next Steps

Quickstart Guide

Configuration

Commands

Development

Deployment

Web Interface

​Getting Help

Build docs developers (and LLMs) love

Installation Methods

Prerequisites

Common Requirements (All Methods)

Method-Specific Requirements

Method 1: Docker (Recommended)

Step 1: Install Docker

Step 2: Prepare Configuration Files

Step 3: Create Environment File

Step 4: Create Configuration File

Step 5: Download Database Schema

Step 6: Create Docker Compose File

Step 7: Launch Faculty Bot

Docker Management Commands

Method 2: Automated Scripts

Linux Installation

Windows Installation

Method 3: Manual Installation

Step 1: Install Rust Toolchain

Step 2: Install System Dependencies

Step 3: Clone and Build

Step 4: Set Up PostgreSQL

Step 5: Configure Environment

Step 6: Run Faculty Bot

Step 7: Set Up Process Manager

Post-Installation Steps

1. Register Slash Commands

2. Configure ImageMagick (For Meal Plans)

3. Test Verification System

4. Configure Channel Permissions

Updating Faculty Bot

Troubleshooting

Security Best Practices

Next Steps

Getting Help