openreader/scripts/OPENREADER_SETUP.md

OpenReader WebUI Setup Guide

Document reader with high-quality text-to-speech using Groq's Orpheus TTS.

URL: http://localhost:3003

Architecture

┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  OpenReader WebUI   │────▶│  Groq TTS Proxy  │────▶│   Groq API      │
│  (Docker :3003)     │     │  (Python :8880)  │     │   (Orpheus)     │
└─────────────────────┘     └──────────────────┘     └─────────────────┘
         │
         ▼
┌─────────────────────┐
│  nginx (SSL :443)   │
│  your-domain.com
└─────────────────────┘

Components

Component	Location	Port	Purpose
OpenReader WebUI	Docker container	3003	PDF/EPUB reader UI
Groq TTS Proxy	scripts/groq-tts-proxy.py	8880	Adds /voices endpoint, proxies to Groq
nginx	/etc/nginx/conf.d/openreader.conf	443	SSL termination, reverse proxy

Files

scripts/
├── openreader-webui.sh      # Startup script (run this to start everything)
├── groq-tts-proxy.py        # Python proxy server for Groq TTS
├── .env                     # Contains GROQ_API_KEY
└── OPENREADER_SETUP.md      # This file

Quick Start

Start Services

./scripts/openreader-webui.sh

Check Status

# Check if proxy is running
curl http://localhost:8880/v1/audio/voices

# Check if container is running
docker ps | grep openreader

# Check proxy logs
cat /tmp/groq-proxy.log

# Check container logs
docker logs openreader-webui --tail 50

Stop Services

# Stop container
docker stop openreader-webui

# Stop proxy
pkill -f groq-tts-proxy.py

Configuration

Environment Variable

Create a .env file in the scripts/ directory:

GROQ_API_KEY=gsk_xxxxx

Available Voices

Groq Orpheus supports 6 voices:

• Male: troy, austin, daniel
• Female: autumn, diana, hannah

TTS Model

• Model: canopylabs/orpheus-v1-english
• Output: WAV audio, 24kHz, 16-bit mono

nginx Configuration

File: /etc/nginx/conf.d/openreader.conf

server {
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3003;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

Groq TTS Proxy

The proxy (groq-tts-proxy.py) serves two purposes:

1. Provides /v1/audio/voices endpoint - OpenReader needs this to populate the voice dropdown, but Groq doesn't have this endpoint
2. Proxies TTS requests - Forwards /v1/audio/speech requests to Groq with correct model name and response format

Endpoints

Endpoint	Method	Description
/	GET	Health check
/v1/audio/voices	GET	Returns available voices
/v1/audio/speech	POST	Generates speech audio

Request Example

curl -X POST http://localhost:8880/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello world", "voice": "troy"}' \
  -o output.wav

Docker Container

Image

ghcr.io/richardr1126/openreader-webui:latest

Volume

Documents are stored in Docker volume openreader_docstore mounted at /app/docstore

Environment Variables

Variable	Value	Description
API_KEY	none	Not needed (proxy handles auth)
API_BASE	http://host.docker.internal:8880/v1	Points to local proxy

Troubleshooting

Voices not showing in dropdown

# Check proxy is running
curl http://localhost:8880/v1/audio/voices

# If not running, restart
./scripts/openreader-webui.sh

TTS not working / Server not responding

# Test proxy directly
curl -X POST http://localhost:8880/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "voice": "troy"}' \
  -o /tmp/test.wav

# Check if valid audio
file /tmp/test.wav
# Should show: RIFF (little-endian) data, WAVE audio...

Document not loading (stuck on spinner)

The document may have been deleted when the container was recreated. Re-upload the file.

Port 8880 already in use

lsof -ti:8880 | xargs -r kill -9

SSL certificate renewal

Certbot auto-renews. Manual renewal:

sudo certbot renew

Supported File Types

• PDF
• EPUB
• TXT
• MD (Markdown)
• DOCX

Limitations

• Groq Orpheus has a 200 character limit per TTS request
• OpenReader handles chunking automatically
• Only English voice model available via Groq (Arabic Saudi dialect also available)

Links

• OpenReader WebUI GitHub
• Groq Orpheus TTS Docs
• Groq Console