📚🤖 Uni Mannheim Library Occupancy Bot

A Discord bot that tracks seat availability in the University of Mannheim libraries (A3, A5, Ehrenhof, Schneckenhof). It updates Discord with live embeds and saves occupancy data to MySQL for analysis.

---

📑 Table of Contents

• 📸 Preview
• ✨ Features
• 🚀 Getting Started
  • 1. Clone the repository
  • 2. Install dependencies
  • 3. Create a Discord Bot
  • 4. Configure environment
• ▶️ Running the Bot
• 🐳 Running with Docker
  • Option A — Bot only (no database)
  • Option B — Bot + bundled MySQL (self-hosted)
  • Automatic updates from GitHub (Watchtower)
• 🛠️ Configuration
  • Environment Variables
  • Database Schema
• 💡 Ideas for Extensions
• ⚖️ Legal & Ethical Notes
• 📜 License

---

📸 Preview

Here’s how the bot looks in action:

---

✨ Features

• 🔄 Automatic updates every 2.5 minutes
• 🕔 Live opening hours directly scraped from each library page
• 🪑 Seats information: occupied, free, and percentage
• 📌 Location info for each library branch
• 📊 MySQL persistence for later analysis and visualization
• 🎭 Fun rotating status messages (e.g. “listening to loud students in the library”)

---

🚀 Getting Started

1. Clone the repository

git clone https://github.com/niclassslua/unimannheim-bib-discord-bot.git
cd unimannheim-bib-discord-bot

2. Install dependencies

npm install

3. Create a Discord Bot

1. Go to the Discord Developer Portal.
2. Click New Application → give it a name → Create.
3. Navigate to Bot → click Add Bot.
4. Copy the Bot Token (use this in your .env file as DISCORD_TOKEN).
5. Under Privileged Gateway Intents, enable:
   • ✅ Message Content Intent
   • ✅ Server Members Intent
6. Under OAuth2 → URL Generator:
   • Select bot and applications.commands.
   • Under Bot Permissions, choose:
     • Send Messages
     • Embed Links
     • Read Message History
   • Copy the generated URL and add the bot to your server.

4. Configure environment

Copy the provided .env.example and fill in your own values:

cp .env.example .env

Edit .env and add:

• 🎫 Your Discord Bot Token
• 🗄️ Your MySQL database credentials (only if you enable DB persistence)
• 💬 The Discord Channel ID + message IDs for each embed

---

▶️ Running the Bot

Development (with auto-reload)

npm run dev

Production

npm start

The bot will:

1. Login to Discord
2. Fetch the latest occupancy data
3. Update the pinned messages in your chosen channel
4. Save a snapshot every 4 update cycles to your database (if DB is enabled)

---

🐳 Running with Docker

This project provides two Compose setups depending on whether you want persistence:

Option A — Bot only (no database)

Use this if you don’t want to store data (Discord updates only).
Compose file: docker-compose.bot.yml

docker compose -f docker-compose.bot.yml up -d --build

This sets USE_DB=false explicitly so the bot skips all DB writes.

Option B — Bot + bundled MySQL (self-hosted)

Use this to run the bot with its own MySQL database.
Compose file: docker-compose.dev.yml

docker compose -f docker-compose.dev.yml up -d --build

• MySQL is started alongside the bot.
• The schema is auto-created from resources/sql/init.sql.
• Data persists in the db_data volume.
• The bot connects internally to the db service with USE_DB=true.

---

🛠️ Configuration

Environment Variables (.env)

# Discord
DISCORD_TOKEN=your-bot-token-here
TEXT_CHANNEL_ID=123456789012345678
MESSAGE_A3=123456789012345678
MESSAGE_A5=123456789012345678
MESSAGE_EHRENHOF=123456789012345678
MESSAGE_SCHNECKENHOF=123456789012345678

# Database
USE_DB=true                 # set false to disable DB writes entirely
DB_HOST=localhost
DB_USER=your-db-user
DB_PASSWORD=your-db-password
DB_DATABASE=your-db-name

# Scraper
OCCUPANCY_URL=https://www.bib.uni-mannheim.de/standorte/freie-sitzplaetze/
DEBUG=false

Database Schema

The bot writes snapshots into a table belegung:

CREATE TABLE belegung (
  id INT AUTO_INCREMENT PRIMARY KEY,
  bib VARCHAR(50) NOT NULL,
  percentage INT NOT NULL,
  occupied INT NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

---

💡 Ideas for Extensions

• 📈 Grafana dashboard for historical occupancy data
• 🌐 REST API for other apps to consume the data

---

⚖️ Legal & Ethical Notes

• This project scrapes the public seat availability page of the University of Mannheim Library.
• According to the robots.txt, the relevant path /standorte/freie-sitzplaetze/ is not disallowed for crawlers.
• The data is publicly accessible without authentication and intended to inform students about seat occupancy.
• Requests are made only once every 150 seconds, resulting in negligible server load.
• The bot is non-commercial and purely for student convenience (Discord notifications).
• I fully respect the rights of the University Library and will adapt or disable the scraper immediately if requested.

---

📜 License

This project is licensed under the MIT License.
Feel free to use, modify, and share — just credit the author.

---

Made with ❤️