matrix-quotes-bot/README.md

# Ancestor Quote Bot 🎃

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

## Quick Start

```bash
# 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)
```bash
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
```bash
docker run --rm \
  -v $(pwd)/.env:/app/.env \
  ancestor-quote-bot
```

### Option 3: Use docker-compose.yml (Production)
```bash
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](https://matrix.org/docs/projects/registration/matrix-registration-api) or your Matrix admin panel to register a bot account.

## License

ISC