matrix-quotes-bot/README.md

Ancestor Quote Bot 🎃

A Matrix chatbot that responds to !quote commands with random quotes from Darkest Dungeons.

Quick Start

# 1. Update .env file (create from template)
cp .env.example .env
# Edit .env with your MATRIX_ACCESS_TOKEN and MATRIX_HOME_SERVER

# 2. Build Docker image
docker build -t ancestor-quote-bot .

# 3. Run the bot
docker run --rm \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_token_here \
  ancestor-quote-bot

Deployment Options

Option 1: Pass env vars via docker run (Recommended for Docker)

docker run --rm \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_access_token_here \
  -e BOT_COMMAND=!quote \
  ancestor-quote-bot

Option 2: Mount .env file directly

docker run --rm \
  -v $(pwd)/.env:/app/.env \
  ancestor-quote-bot

Option 3: Use docker-compose.yml (Production)

docker compose up -d
# Or with custom env:
docker compose up -d \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_access_token_here

Configuration

Variable	Description	Default
MATRIX_HOME_SERVER	Matrix homeserver URL (e.g., https://matrix.org)	https://matrix.org
MATRIX_ACCESS_TOKEN	Bot access token for authentication	REQUIRED
BOT_COMMAND	Command trigger to request a quote	!quote

How It Works

1. The bot connects to your Matrix homeserver using the provided access token
2. Once joined to a room, it listens for messages containing the trigger command
3. When triggered, it selects a random quote from quotes.json and replies instantly

Getting an Access Token

Use this or your Matrix admin panel to register a bot account.

License

ISC