# Deployment Guide

Complete guide for deploying RedditBot in various environments.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Local Development](#local-development)
3. [Docker Deployment](#docker-deployment)
4. [Docker Compose](#docker-compose)
5. [Dokploy Deployment](#dokploy-deployment)
6. [Production Considerations](#production-considerations)
7. [Monitoring & Maintenance](#monitoring--maintenance)
8. [Troubleshooting](#troubleshooting-1)

---

## 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](https://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

```bash
git clone <repository-url>
cd RedditBot
npm install
```

### 2. Configure

Create `config.yaml`:

```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:

```bash
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

```bash
# 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

```bash
docker build -t reddit-bot .
```

### Run the Container

```bash
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

```yaml
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

```bash
# 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

```yaml
# 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

```bash
# 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