RedditBot/docs/deployment.md

Deployment Guide

Complete guide for deploying RedditBot in various environments.

---

Table of Contents

1. Prerequisites
2. Local Development
3. Docker Deployment
4. Docker Compose
5. Dokploy Deployment
6. Production Considerations
7. Monitoring & Maintenance
8. Troubleshooting

---

Prerequisites

Required

Requirement	Version	Notes
Node.js	20.19+ or 22.12+	Required by the locked Vite toolchain
npm	Bundled with Node	Use npm ci for lockfile-exact installs
OpenRouter API Key	-	Sign up at openrouter.ai
Reddit Account	-	With DM permissions enabled

Recommended

Requirement	Notes
1 GB RAM	Minimum for browser automation
1 CPU core	More for higher message throughput
5 GB disk	For database, media, and browser data

---

Local Development

1. Clone and Install

git clone <repository-url>
cd RedditBot
npm install

2. Configure

Create config.yaml:

reddit:
  subreddits:
    - gonewild
  pollInterval: 15
  targetGender: "F"
  sellerKeywords:
    - seller
    - onlyfans

openrouter:
  apiKey: "sk-or-v1-your-key-here"
  model: "meta-llama/llama-3.2-90b-vision-preview"
  fallbackModels:
    - "google/gemini-2.0-flash-001"

rateLimit:
  minDelayMs: 30000
  maxMessagesPerHour: 20
  jitterMs: 15000

browser:
  sessionDir: "./data/browser-session"
  dryRun: true

database:
  path: "./data/reddit-bot.db"

web:
  port: 3000

dryRun: true  # Start in dry run mode

Set environment variables:

export OPENROUTER_API_KEY="sk-or-v1-your-key"
export WEB_DASHBOARD_TOKEN="long-random-secret"

3. Import account session

Start the dashboard, then upload a combined Reddit and Matrix dump created by the local Chrome extension. Until both identities verify, account work remains paused.

4. Start the Bot

# Terminal 1: backend with TypeScript execution
npm run dev

# Terminal 2: Vite dashboard; proxies /api to port 3000
npm run dashboard:dev

# Production: compile server and dashboard, then start
npm run build
npm start

5. Access Dashboard

Open the Vite URL (normally http://localhost:5173) during frontend development. Production dashboard checks use http://localhost:3000.

---

Docker Deployment

Build the Image

docker build -t reddit-bot .

Run the Container

docker run -d \
  --name reddit-bot \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -e OPENROUTER_API_KEY=sk-or-v1-your-key \
  -e WEB_DASHBOARD_TOKEN=long-random-secret \
  reddit-bot:latest

Dockerfile behavior

The image is based on the Playwright Jammy image because the remaining authenticated browser operations need Chromium and its system libraries. It does not install a display server, VNC, or consumer Google Chrome.

That build produces both dist/ for the Express server and apps/dashboard/dist/ for Vite assets. Port 3000 serves the dashboard/API and the container starts the Node process directly. This is a single-stage image and retains development dependencies needed by the current build/runtime layout.

---

Docker Compose

docker-compose.yml

version: '3.8'

services:
  reddit-bot:
    build: .
    container_name: reddit-bot
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - WEB_DASHBOARD_TOKEN=${WEB_DASHBOARD_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:3000/api/stats"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Start with Compose

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and start
docker compose up -d --build

# View logs
docker compose logs -f reddit-bot

# Stop
docker compose down

# Restart
docker compose restart

---

Dokploy Deployment

Dokploy is a self-hosted platform for deploying applications. See DOKPLOY_DEPLOY.md for detailed instructions.

Quick Start

1. Create Application: In Dokploy dashboard, create a new Docker application
2. Set Environment Variables:
   • OPENROUTER_API_KEY
   • WEB_DASHBOARD_TOKEN
3. Mount Volume: Mount ./data for persistent storage
4. Set Port: Map container port 3000 to host port
5. Deploy: Push to repository and trigger deployment

Dokploy Configuration

# Dokploy-specific settings
app:
  type: docker
  repository: <your-repo>
  branch: main
  dockerfilePath: Dockerfile
  
  environment:
    OPENROUTER_API_KEY: $OPENROUTER_API_KEY
    WEB_DASHBOARD_TOKEN: $WEB_DASHBOARD_TOKEN
  
  ports:
    - container: 3000
      host: 3000
  
  volumes:
    - source: reddit-bot-data
      target: /app/data
      type: bind
  
  restartPolicy: unless-stopped

---

Production Considerations

Security

1. Network Isolation: Keep the dashboard on a trusted network during the migration cutover
2. Environment Variables: Never commit credentials; use secrets management
3. Dashboard Access: Authenticated Express hosting for React assets, API, SSE, debug routes, and private media is a required cutover gate, not a currently proven guarantee
4. Browser Data: Protect data/browser/ directory

Performance

1. Account dumps: Delete downloaded dumps after the dashboard verifies them
2. WAL Mode: SQLite WAL mode is enabled by default for concurrent reads
3. Rate Limiting: Adjust based on Reddit account age and trust level
4. Message Volume: Start low (10-20/hour) and increase gradually

Reliability

1. Auto-restart: Use restart: unless-stopped in Docker
2. Health Checks: Monitor /api/stats endpoint
3. Logging: Review logs regularly for errors
4. Backups: Regularly backup data/reddit-bot.db

Monitoring

1. Dashboard: Check web dashboard for real-time stats
2. Response Rate: Monitor response rates per strategy/subreddit
3. Error Rate: Watch for AI refusals, send failures
4. Browser Health: Verify session isn't expired

Scaling

RedditBot is designed as a single-instance application. For scaling:

1. Multiple Accounts: Run separate instances per Reddit account
2. Subreddit Split: Distribute subreddits across instances
3. Centralized DB: Consider moving to PostgreSQL for multi-instance

---

Monitoring & Maintenance

Daily Checks

• Dashboard shows bot is running
• Response rate is reasonable (>10%)
• No repeated errors in logs
• Browser session is active

Weekly Tasks

• Review analytics (strategy performance, subreddit performance)
• Check disk usage (media files, database)
• Verify backup is working
• Review successful messages for quality

Monthly Tasks

• Backup database
• Review and update strategy variants
• Check for OpenRouter model updates
• Review and update seller keywords
• Verify browser session is still valid

Backup Procedure

# Stop the bot
docker compose stop

# Backup database
cp data/reddit-bot.db data/reddit-bot.db.backup.$(date +%Y%m%d)

# Backup browser session (optional)
tar czf data/browser.backup.$(date +%Y%m%d).tar.gz data/browser/

# Restart the bot
docker compose start

---

Troubleshooting

Bot Won't Start

Symptom: Bot exits immediately on startup.

Steps:

1. Check logs: docker compose logs reddit-bot
2. Verify config.yaml syntax
3. Verify environment variables are set
4. Check for Zod validation errors in logs

Account Import Fails

Symptom: Account work stays paused or import verification fails.

Steps:

1. Sign in to Reddit in local Chrome
2. Open Reddit Chat and wait for the extension badge to show OK
3. Export and upload a new combined session dump
4. Check logs for Reddit or Matrix identity errors

AI Analysis Fails

Symptom: All messages show "AI refusal" or analysis errors.

Steps:

1. Verify API key is valid and has balance
2. Check model availability on OpenRouter
3. Try changing to a different model
4. Review logs for specific error messages

High Error Rate

Symptom: Many messages fail to send.

Steps:

1. Check rate limiting (reduce maxMessagesPerHour)
2. Increase minDelayMs and jitterMs
3. Check for IP bans (try different network)
4. Review Reddit account standing

Dashboard Not Accessible

Symptom: Cannot reach http://localhost:3000.

Steps:

1. Verify bot is running (docker compose ps)
2. Check port is not in use: lsof -i :3000
3. Verify firewall allows port 3000
4. Check web.port in config.yaml

Database Issues

Symptom: Database errors or corruption.

Steps:

1. Stop the bot
2. Backup the database
3. Try opening with SQLite viewer to check integrity
4. If corrupted, restore from backup
5. Consider enabling automatic backups