Skip to content

Stremthru Service Documentation

Table of Contents

  1. Overview
  2. Architecture
  3. Configuration Details
  4. Integration Points
  5. Supported Debrid Services
  6. Common Use Cases
  7. API Endpoints
  8. Security Considerations
  9. Troubleshooting
  10. Backup Considerations

Overview

Stremthru is a streaming proxy service that acts as a companion for Stremio and other streaming applications. It provides a unified API for accessing content from multiple debrid providers, enabling IP restriction bypassing, improved compatibility, and centralized management of streaming services.

Key Features: - Multi-Debrid Support: Integrates with Real-Debrid, AllDebrid, Premiumize, Debrid-Link, and other services - Content Proxying: Routes streaming requests through the proxy to bypass IP restrictions - Authentication Management: Handles credentials for multiple debrid services - Caching Layer: Uses Redis for performance optimization - HTTP(S) Proxy Support: Tunnels traffic when direct access is blocked - Byte Serving: Supports range requests for streaming optimization

The service is deployed at https://stremthru.rbnk.uk and integrates with our Redis cache and PostgreSQL database infrastructure.

Architecture

Container Configuration

  • Image: muniftanjim/stremthru:latest
  • Port: 8080 (internal), exposed via Traefik
  • Networks:
  • traefik_proxy (external access via HTTPS)
  • cache_redis_network (Redis caching)
  • supabase_internal (PostgreSQL database)

Service Dependencies

graph TD
    A[Stremthru] --> B[Redis Cache DB1]
    A --> C[PostgreSQL Supabase]
    A --> D[External Debrid APIs]
    A --> E[External Metadata APIs]

    D --> F[Real-Debrid]
    D --> G[AllDebrid]
    D --> H[Premiumize]
    D --> I[Debrid-Link]

    E --> J[TMDB API]
    E --> K[Trakt API]
    E --> L[GitHub API]

    M[Clients] --> N[Traefik]
    N --> A

    style A fill:#f9f,stroke:#333,stroke-width:4px
    style B fill:#ff9,stroke:#333,stroke-width:2px
    style C fill:#9ff,stroke:#333,stroke-width:2px

Data Flow

  1. Client Request: Streaming application requests content via Stremthru API
  2. Authentication: Proxy authorization validates user credentials
  3. Store Lookup: Determines appropriate debrid service for content
  4. Cache Check: Checks Redis cache for existing metadata/links
  5. Debrid API Call: Fetches content information from debrid service
  6. Content Proxy: Routes streaming requests through Stremthru proxy
  7. Response: Returns streaming URL or proxied content to client

Configuration Details

Environment Variables

Core Configuration

# Service Configuration
STREMTHRU_PROXY_URL=https://stremthru.rbnk.uk
STREMTHRU_BASE_URL=https://stremthru.rbnk.uk
STREMTHRU_LOG_LEVEL=info
STREMTHRU_STORE_PATH=/data

# Authentication (comma-separated credentials)
STREMTHRU_PROXY_AUTH=username:password
STREMTHRU_AUTH_ADMIN=admin_username

Store Authentication

# Format: username:store_name:store_token
STREMTHRU_STORE_AUTH=home:realdebrid:TOKEN,home:alldebrid:TOKEN

Database & Cache

# Redis Cache (Database 1)
STREMTHRU_REDIS_URI=redis://:password@cache-redis:6379/1

# PostgreSQL Database
STREMTHRU_DATABASE_URI=postgresql://postgres:password@db:5432/postgres?sslmode=disable

External Integrations

# GitHub Integration
STREMTHRU_INTEGRATION_GITHUB_USER=username
STREMTHRU_INTEGRATION_GITHUB_TOKEN=github_pat_token

# TMDB (The Movie Database)
STREMTHRU_INTEGRATION_TMDB_ACCESS_TOKEN=bearer_token

# Trakt.tv
STREMTHRU_INTEGRATION_TRAKT_CLIENT_ID=client_id
STREMTHRU_INTEGRATION_TRAKT_CLIENT_SECRET=client_secret

Debrid Service API Keys

# Real-Debrid
REAL_DEBRID_API_KEY=your_api_key

# AllDebrid
ALL_DEBRID_API_KEY=your_api_key

# Premiumize
PREMIUMIZE_API_KEY=your_api_key

# Debrid-Link
DEBRID_LINK_API_KEY=your_api_key

# Additional services...

Optional Security

# Password protection for web interface
STREMTHRU_PASSWORD=changeme

# External proxy for outgoing requests
STREMTHRU_EXTERNAL_PROXY=http://proxy.example.com:8080

Configuration Files

  • Data Directory: /data (persistent storage for cache and metadata)
  • Config Directory: /app/assets (mounted from ./config)

Integration Points

1. Redis Cache Integration

  • Database: Cache Redis DB 1
  • Purpose: Stores metadata, API responses, and streaming URLs
  • Benefits: Reduces API calls to debrid services, improves response times
  • Stale Time: Configurable cache expiration for different content types

2. PostgreSQL Database

  • Connection: Via Supabase internal network
  • Purpose: Persistent storage for user data, analytics, and configuration
  • Schema: Manages user preferences, usage statistics, and service health

3. External API Integrations

Metadata Services

  • TMDB: Movie and TV show metadata, images, ratings
  • Trakt.tv: User tracking, watchlists, recommendations
  • GitHub: Service updates, configuration management

Debrid Services

  • Real-Debrid: Premium file hosting and streaming
  • AllDebrid: Multi-hoster premium service
  • Premiumize: Cloud storage and premium downloading
  • Debrid-Link: Debrid service aggregator
  • Additional: PikPak, Seedr, EasyNews, Put.io, Offcloud

Supported Debrid Services

Primary Services

Real-Debrid

  • Features: Premium file hosting, instant streaming, torrent caching
  • API: REST API with rate limiting
  • Configuration: REAL_DEBRID_API_KEY
  • Bandwidth: Unlimited on premium plans

AllDebrid

  • Features: Multi-hoster support, torrent downloading, streaming
  • API: RESTful with JSON responses
  • Configuration: ALL_DEBRID_API_KEY
  • Specialty: Wide hoster support, reliable uptime

Premiumize

  • Features: Cloud storage, VPN, torrent handling
  • API: Comprehensive REST API
  • Configuration: PREMIUMIZE_API_KEY
  • Benefits: Built-in VPN, large storage quotas

Additional Services

  • Debrid-Link: Service aggregator with multi-provider support
  • PikPak: Cloud storage with streaming capabilities
  • Seedr: Browser-based torrent client with streaming
  • EasyNews: Usenet provider with web-based downloading
  • Put.io: Cloud torrent client with streaming interface
  • Offcloud: Remote cloud downloading service

Service Selection Logic

Stremthru automatically selects the optimal debrid service based on: 1. Content Availability: Which service has the requested content 2. User Preferences: Configured priority in STREMTHRU_STORE_AUTH 3. Service Health: API response times and error rates 4. Quota Management: Available bandwidth and download limits

Common Use Cases

1. IP Restriction Bypassing

Problem: Debrid services restrict simultaneous connections from the same IP Solution: Stremthru proxies all requests through its server IP 

# Multiple devices can stream simultaneously
# All traffic appears to come from Stremthru server

2. Multi-Location Access

Problem: Geographic restrictions on debrid service access Solution: Centralized proxy allows access from any location 

# Configure proxy authorization
STREMTHRU_PROXY_AUTH=user1:password1,user2:password2

3. Unified API Access

Problem: Different APIs for each debrid service Solution: Single API endpoint for all services 

# Single configuration handles multiple services
STREMTHRU_STORE_AUTH=user:realdebrid:token,user:alldebrid:token

4. Improved Compatibility

Problem: Some players don't work well with direct debrid links Solution: Proxied streams provide better compatibility 

# Works with Infuse, Plex, Kodi, and other players
# Handles byte-range requests properly

5. Analytics and Monitoring

Problem: No visibility into debrid service usage Solution: Centralized logging and analytics via database 

# Track usage patterns, popular content, service health
# Monitor API quotas and bandwidth usage

API Endpoints

Authentication

POST /auth
Content-Type: application/json
X-StremThru-Authorization: Basic base64(username:password)

Content Endpoints

# Get content information
GET /content/{id}
X-StremThru-Authorization: Basic base64(username:password)

# Stream content (proxied)
GET /stream/{id}
Range: bytes=0-1048576
X-StremThru-Authorization: Basic base64(username:password)

Store Management

# List available stores
GET /stores
X-StremThru-Authorization: Basic base64(username:password)

# Store health check
GET /stores/{store_name}/health
X-StremThru-Authorization: Basic base64(username:password)

Cache Management

# Clear cache for specific content
DELETE /cache/{id}
X-StremThru-Authorization: Basic base64(username:password)

# Cache statistics
GET /cache/stats
X-StremThru-Authorization: Basic base64(username:password)

Health and Status

# Service health
GET /health

# Service status and version
GET /status

# Metrics (if enabled)
GET /metrics

Security Considerations

1. Authentication & Authorization

  • Proxy Auth: Username/password combinations for service access
  • Admin Access: Separate admin credentials for management operations
  • Store Credentials: Securely stored debrid service API keys

2. Network Security

  • HTTPS Only: All external traffic encrypted via Traefik
  • Internal Networks: Services communicate over isolated Docker networks
  • Firewall: No direct external access to service ports

3. Credential Management

  • Environment Variables: Sensitive data stored in .env files (640 permissions)
  • Secret Rotation: Regular rotation of API keys and passwords
  • Audit Logging: Track authentication attempts and API usage

4. Data Protection

  • Encryption in Transit: TLS for all external communications
  • Cache Security: Redis password protection, isolated database
  • Database Security: PostgreSQL with role-based access control

5. Rate Limiting

  • API Quotas: Respect debrid service rate limits
  • Connection Limits: Per-user concurrent connection restrictions
  • Abuse Prevention: Monitor for suspicious usage patterns

Troubleshooting

Common Issues

1. Authentication Failures

Symptoms: 401/403 errors, login rejections Diagnosis: 

# Check service logs
docker compose -f stremthru/docker-compose.yml logs -f

# Verify credentials
echo $STREMTHRU_PROXY_AUTH | base64 -d

# Test authentication
curl -H "X-StremThru-Authorization: Basic $(echo 'user:pass' | base64)" \
  https://stremthru.rbnk.uk/auth

Solutions: - Verify STREMTHRU_PROXY_AUTH format: username:password - Check STREMTHRU_STORE_AUTH format: username:store:token - Ensure debrid service API keys are valid

2. Cache Issues

Symptoms: Slow responses, repeated API calls, stale data Diagnosis: 

# Check Redis connection
docker exec cache-redis redis-cli -a "$REDIS_PASSWORD" ping

# Monitor cache usage
docker exec cache-redis redis-cli -a "$REDIS_PASSWORD" info memory

# Check database selection
docker exec cache-redis redis-cli -a "$REDIS_PASSWORD" -n 1 info keyspace

Solutions: - Verify Redis connection string format - Check Redis password and database number - Clear cache if corrupted: docker exec cache-redis redis-cli -a "$REDIS_PASSWORD" -n 1 flushdb

3. Debrid Service Failures

Symptoms: 5xx errors, timeouts, invalid links Diagnosis: 

# Test debrid service APIs directly
curl -H "Authorization: Bearer $REAL_DEBRID_API_KEY" \
  https://api.real-debrid.com/rest/1.0/user

# Check service status
curl https://stremthru.rbnk.uk/stores/realdebrid/health

Solutions: - Verify API keys are current and valid - Check debrid service status pages - Rotate API keys if needed - Update service endpoints if changed

4. Database Connectivity

Symptoms: Database connection errors, data not persisting Diagnosis: 

# Test PostgreSQL connection
docker exec supa-db psql -U postgres -c "SELECT version();"

# Check database URI format
echo $STREMTHRU_DATABASE_URI

Solutions: - Verify PostgreSQL credentials and connection string - Ensure Supabase stack is running - Check network connectivity between containers

5. Proxy and Networking

Symptoms: Connection timeouts, proxy errors, geo-blocking Diagnosis: 

# Test external connectivity
docker exec stremthru curl -I https://api.real-debrid.com

# Check proxy configuration
curl -x http://proxy:8080 https://stremthru.rbnk.uk/health

Solutions: - Configure STREMTHRU_EXTERNAL_PROXY if needed - Check firewall rules and network policies - Verify DNS resolution

Log Analysis

# View real-time logs
docker compose -f stremthru/docker-compose.yml logs -f

# Filter for specific issues
docker compose -f stremthru/docker-compose.yml logs | grep -i error

# Export logs for analysis
docker compose -f stremthru/docker-compose.yml logs --since 24h > stremthru-debug.log

Performance Monitoring

# Container resource usage
docker stats stremthru

# Redis cache statistics
docker exec cache-redis redis-cli -a "$REDIS_PASSWORD" -n 1 info stats

# Database performance
docker exec supa-db psql -U postgres -c "SELECT * FROM pg_stat_activity WHERE application_name LIKE '%stremthru%';"

Backup Considerations

Critical Data

  1. Configuration Files:
  2. .env file with credentials and settings

  3. docker-compose.yml with service definition

  4. Persistent Data:

  5. /data directory (application data, logs, metadata)
  6. Database records (user preferences, analytics)
  7. Redis cache (optional, can be rebuilt)

Backup Strategy

# Configuration backup (included in infrastructure backup)
cp stremthru/.env _backup/stremthru-env-$(date +%Y%m%d)
cp stremthru/docker-compose.yml _backup/stremthru-compose-$(date +%Y%m%d)

# Data directory backup
tar -czf _backup/stremthru-data-$(date +%Y%m%d).tar.gz stremthru/data/

# Database backup (included in Supabase backup)
# Redis cache backup (optional - can be rebuilt from debrid APIs)

Restoration Process

  1. Service Stop: docker compose -f stremthru/docker-compose.yml down
  2. Restore Configuration: Copy .env and docker-compose.yml
  3. Restore Data: Extract data directory backup
  4. Database Restore: Use Supabase restoration procedures
  5. Service Start: docker compose -f stremthru/docker-compose.yml up -d
  6. Cache Warmup: Cache will rebuild automatically on first requests

Backup Schedule

  • Daily: Included in infrastructure backup (4 AM via Rclone to Cloudflare R2)
  • Retention: 14 days as per infrastructure backup policy
  • Critical: .env file contains sensitive API keys - secure backup required

Recovery Testing

# Test configuration validity
docker compose -f stremthru/docker-compose.yml config

# Verify service health after restoration
curl https://stremthru.rbnk.uk/health

# Test debrid service connectivity
curl -H "X-StremThru-Authorization: Basic $(echo 'user:pass' | base64)" \
  https://stremthru.rbnk.uk/stores

Integration with Infrastructure

Stremthru integrates seamlessly with the existing infrastructure:

  • Monitoring: Health checks via Prometheus, alerts via Grafana
  • Logging: Logs aggregated by Loki, viewable in Grafana
  • Notifications: Service alerts via ntfy and Apprise
  • Backup: Included in automated infrastructure backup system
  • Updates: Managed by Watchtower for automated container updates
  • DNS: Managed via Cloudflare DNS with automatic SSL certificates

For additional support and configuration details, refer to: - Official Stremthru Repository - Infrastructure Monitoring Guide - Backup and Recovery Documentation