TestPostsBot/README.md

# Reddit TestPostsBot

A Reddit bot that makes test posts to your subreddit when triggered via private messages by moderators.

## How It Works

1. The bot runs continuously and listens for private messages sent to its account
2. When a moderator sends a message containing a trigger keyword, the bot checks the wiki config
3. If the trigger is found and valid, the bot posts the configured posts to the subreddit
4. The bot replies to the moderator confirming success or failure

## Setup

### Environment Variables

Set these variables via environment or directly in `bot.py`:

- `REDDIT_CLIENT_ID`: Your Reddit app's client ID
- `REDDIT_CLIENT_SECRET`: Your Reddit app's client secret
- `REDDIT_USERNAME`: The bot account's username
- `REDDIT_PASSWORD`: The bot account's password
- `REDDIT_USER_AGENT`: (Optional) Custom user agent string
- `SUBREDDIT`: The subreddit to post to (without the /r/)
- `WIKI_PAGE`: (Optional) Wiki page for config (default: `testpostsbot_config`)

### Wiki Configuration

Create a wiki page in your subreddit named `testpostsbot_config` (or set `WIKI_PAGE` env var) with YAML formatted triggers and posts:

```yaml
posts:
  - trigger: "summer-schedule"
    posts:
      - title: "Summer Announcement Post"
        body: "This is the summer announcement."
      - title: "Summer Rules Update"
        body: "New summer rules are now in effect."

  - trigger: "test"
    posts:
      - title: "Test Post"
        body: "This is a test post."

  - trigger: "weekly-thread"
    posts:
      - title: "Weekly Discussion Thread"
        body: |
          This is the weekly discussion thread.
          Feel free to discuss anything related to the subreddit.
```

Each trigger can have one or multiple posts. Posts are made in order with a 2-second delay between each to avoid rate limiting.

### Triggering Posts

To trigger posts, send a private message to the bot account containing the trigger keyword. For example:

- Message: "Can you run summer-schedule?" → Posts the summer schedule posts
- Message: "Trigger: test" → Posts the test post
- Message: "Please post weekly-thread" → Posts the weekly discussion thread

Only moderators of the subreddit can trigger posts.

## Running the Bot

### Docker

```bash
docker build -t testpostsbot .
docker run \
  --env REDDIT_CLIENT_ID=your_client_id \
  --env REDDIT_CLIENT_SECRET=your_client_secret \
  --env REDDIT_USERNAME=bot_username \
  --env REDDIT_PASSWORD=bot_password \
  --env SUBREDDIT=your_subreddit \
  testpostsbot
```

### Docker Compose

```bash
# Edit prod.env with your credentials, then:
docker-compose up
```

#### Security: Running as Non-Root User

By default, the container runs as a non-root user (UID 1000, GID 1000) for improved security. You can customize the user and group IDs by setting environment variables before running:

```bash
# Use specific user and group IDs
USER_ID=1001 GROUP_ID=1001 docker-compose up

# Use default (1000:1000)
docker-compose up
```

The user and group IDs can also be specified in a `.env` file:

```env
USER_ID=1001
GROUP_ID=1001
REDDIT_CLIENT_ID=your_client_id
REDDIT_CLIENT_SECRET=your_client_secret
REDDIT_USERNAME=bot_username
REDDIT_PASSWORD=bot_password
SUBREDDIT=your_subreddit
WIKI_PAGE=testpostsbot_config
```

### Standalone

```bash
pip install -r requirements.txt
python bot.py
```

## Configuration Notes

- The wiki config is validated on startup. If the YAML is malformed, the bot will not start.
- The config is fetched fresh for each trigger, so you can update the wiki while the bot is running.
- Only the first matching trigger per message is processed.
- All processed messages are tracked in `DB/chat_wiki_requests.txt` to avoid duplicate processing.

## Security

- **Non-Root Execution:** The Docker container runs as a non-root user (UID 1000, GID 1000) by default to minimize security risks. This can be customized via `USER_ID` and `GROUP_ID` environment variables.
- **Credentials:** Store Reddit API credentials in environment variables or `.env` files, never hardcode them.
- **Moderator-Only Commands:** All bot triggers and commands require the sender to be a moderator of the target subreddit.
- **DB Directory:** Processed message IDs are stored in a local `DB/` directory to prevent duplicate processing and maintain stateful operation.