BDFR_Web/DOCKER.md

BDFR Web Interface - Docker Deployment Guide

This guide covers running the BDFR Web Interface with full BDFR backend support using Docker.

Quick Start

Prerequisites

• Docker Engine 20.10 or later
• Docker Compose 2.0 or later
• At least 2GB of free disk space

Basic Setup

1. Clone the repository (if you haven't already):

   git clone <repository-url>
   cd BDFR_Web
   

2. Create required directories:

   mkdir -p downloads data config
   

3. Configure environment variables (optional but recommended):

   cp web_interface/.env.example .env
   # Edit .env with your Reddit OAuth credentials
   

4. Start the container:

   docker-compose up -d
   

5. Access the web interface: Open your browser to http://localhost:8000

Configuration

Environment Variables

Create a .env file in the project root with the following variables:

# Docker User Configuration (Important for file permissions)
# Set these to match your host user's UID/GID to avoid permission issues
# Find your UID/GID by running: id (on Linux/Mac) or wsl id (on Windows WSL)
PUID=1000
PGID=1000

# Reddit OAuth Configuration (Required for authenticated features)
BDFR_CLIENT_ID=your_client_id_here
BDFR_CLIENT_SECRET=your_client_secret_here
BDFR_REDIRECT_URI=http://localhost:8000/auth/callback

# Server Configuration (Optional)
HOST=0.0.0.0
PORT=8000
DEBUG=false

Getting Reddit OAuth Credentials

1. Go to https://www.reddit.com/prefs/apps
2. Click "Create App" or "Create Another App"
3. Fill in the form:
   • Name: BDFR Web Interface (or your choice)
   • App type: Select "web app"
   • Description: (optional)
   • About URL: (optional)
   • Redirect URI: http://localhost:8000/auth/callback
4. Click "Create app"
5. Copy the client ID (under the app name) and client secret

Volume Mounts

The Docker setup uses two volume mounts:

Host Path	Container Path	Purpose
./downloads	/app/downloads	All Reddit downloads are stored here
./data	/app/data	SQLite databases, scheduled tasks, and BDFR configuration

Data Directory Structure:

./data/
├── bdfr-config/          # BDFR configuration and OAuth tokens
│   ├── config.cfg        # BDFR settings
│   ├── log_output.txt    # BDFR logs
│   └── oauth_tokens/     # Reddit authentication tokens
├── scheduled_tasks.db    # Web interface scheduled tasks
└── scheduler_jobs.db     # APScheduler job store

Usage

Managing the Container

Start the container:

docker-compose up -d

Stop the container:

docker-compose down

View logs:

docker-compose logs -f

Restart the container:

docker-compose restart

Rebuild after code changes:

docker-compose up -d --build

Using the Web Interface

1. Navigate to http://localhost:8000
2. Use the web UI to:
   • Download from subreddits
   • Download from users
   • Schedule recurring downloads
   • Monitor active downloads
   • View download history

Using BDFR CLI Inside Container

You can also use the BDFR command-line tool directly:

Enter the container:

docker exec -it bdfr-web-interface bash

Run BDFR commands:

# Download from a subreddit
bdfr download /app/downloads --subreddit Python -L 10

# Download from a user
bdfr download /app/downloads --user reddituser --submitted -L 100

# Archive posts
bdfr archive /app/downloads --subreddit all -L 500

# Clone (download + archive)
bdfr clone /app/downloads --subreddit EarthPorn -L 50

One-line BDFR commands:

# Download without entering the container
docker exec bdfr-web-interface bdfr download /app/downloads --subreddit Python -L 10

# View BDFR version
docker exec bdfr-web-interface bdfr --version

# View BDFR help
docker exec bdfr-web-interface bdfr download --help

Advanced Configuration

Custom Port

To run on a different port, modify docker-compose.yml:

ports:
  - "3000:8000"  # Host port 3000, container port 8000

Or set the PORT environment variable:

PORT=3000

Custom Download Directory

Mount a different host directory for downloads:

volumes:
  - /path/to/your/downloads:/app/downloads
  - ./data:/app/data

BDFR Configuration File

BDFR configuration is automatically stored in ./data/bdfr-config/. You can customize it by creating ./data/bdfr-config/config.cfg:

[DEFAULT]
client_id = your_client_id
client_secret = your_client_secret
scopes = identity, read, history, mysubreddits

[bdfr]
max_wait_time = 120
time_format = %Y-%m-%d_%H-%M-%S

Note: BDFR will automatically create this directory and configuration file on first run.

Resource Limits

Add resource constraints in docker-compose.yml:

services:
  bdfr-web:
    # ... other configuration ...
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 512M

Troubleshooting

Container Won't Start

Check logs:

docker-compose logs bdfr-web

Verify ports aren't in use:

# Windows
netstat -ano | findstr :8000

# Linux/Mac
lsof -i :8000

Rebuild the image:

docker-compose down
docker-compose build --no-cache
docker-compose up -d

Permission Issues

If you encounter permission errors with volumes (e.g., "Permission denied" when creating directories):

Solution 1: Configure PUID/PGID (Recommended)

Set PUID and PGID in your .env file to match your host user:

# Find your UID and GID
id

# Example output: uid=1001(username) gid=1001(groupname)
# Add to .env file:
PUID=1001
PGID=1001

Then restart the container:

docker-compose down
docker-compose up -d

Solution 2: Fix Host Directory Permissions

Linux/Mac:

sudo chown -R $USER:$USER downloads data config
chmod -R 755 downloads data config

TrueNAS/NAS Systems: When using network shares or NAS storage:

1. Find your NAS user's UID/GID (usually in user management settings)
2. Set PUID and PGID in .env to match your NAS user
3. Ensure the NAS user has read/write permissions on mounted shares

Windows: Ensure Docker Desktop has access to the drive where the project is located (Settings → Resources → File Sharing).

Why this matters: The container runs as a specific user (default UID 1000). If your host directories are owned by a different user, the container won't be able to write to them. Setting PUID and PGID tells Docker to run the container as your host user, matching permissions.

Downloads Not Appearing

1. Check volume mounts are correct:

   docker inspect bdfr-web-interface | grep -A 10 Mounts
   

2. Verify download directory inside container:

   docker exec bdfr-web-interface ls -la /app/downloads
   

3. Check container logs for errors:

   docker-compose logs -f bdfr-web
   

Permission Denied Errors

If you see errors like "Permission denied: '/usr/local/lib/python3.11/site-packages/bdfr/default_config.cfg'":

1. Verify the BDFR config directory exists and is writable:

   docker exec bdfr-web-interface ls -la /app/data/bdfr-config
   

2. Check environment variables are set correctly:

   docker exec bdfr-web-interface env | grep BDFR
   

3. If the directory doesn't exist or has wrong permissions:

   docker-compose down
   docker-compose up -d --build
   

OAuth Authentication Issues

1. Verify credentials in .env or docker-compose.yml
2. Ensure redirect URI matches exactly: http://localhost:8000/auth/callback
3. Check Reddit app settings at https://www.reddit.com/prefs/apps
4. Restart container after changing credentials:

   docker-compose restart
   

High Memory Usage

BDFR can use significant memory when downloading large files or many files simultaneously:

1. Monitor memory usage:

   docker stats bdfr-web-interface
   

2. Add memory limits (see Resource Limits above)

3. Reduce concurrent downloads by limiting the number of simultaneous operations

Database Locked Errors

If you see SQLite database locked errors:

1. Ensure only one instance is running:

   docker ps | grep bdfr
   

2. Stop all instances and restart:

   docker-compose down
   docker-compose up -d
   

Maintenance

Backing Up Data

Backup downloads and database:

# Create backup directory
mkdir -p backups

# Backup downloads
tar -czf backups/downloads-$(date +%Y%m%d).tar.gz downloads/

# Backup database
cp -r data/ backups/data-$(date +%Y%m%d)/

Automated backup script (Linux/Mac):

#!/bin/bash
# backup.sh
BACKUP_DIR="backups"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/bdfr-backup-$DATE.tar.gz" downloads/ data/

# Keep only last 7 days of backups
find "$BACKUP_DIR" -name "bdfr-backup-*.tar.gz" -mtime +7 -delete

Updating the Container

Pull latest changes:

git pull origin main
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Update only Docker image:

docker-compose pull
docker-compose up -d

Cleaning Up

Remove stopped containers:

docker-compose down

Remove containers and volumes:

docker-compose down -v

Remove images:

docker-compose down --rmi all

Full cleanup (including downloads):

docker-compose down -v --rmi all
rm -rf downloads/ data/

Security Considerations

Production Deployment

For production use, consider:

1. Use HTTPS: Set up a reverse proxy (nginx/Traefik) with SSL
2. Secure credentials: Use Docker secrets or vault for sensitive data
3. Network isolation: Use custom networks and restrict access
4. Regular updates: Keep the container and dependencies updated
5. Monitor logs: Set up log aggregation and monitoring
6. Backup strategy: Implement automated backups

Example Nginx Reverse Proxy

server {
    listen 80;
    server_name bdfr.example.com;

    location / {
        proxy_pass http://localhost:8000;
        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;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Performance Optimization

Build Performance

Use BuildKit for faster builds:

DOCKER_BUILDKIT=1 docker-compose build

Multi-stage build is already implemented in the Dockerfile to minimize image size.

Runtime Performance

1. Allocate sufficient resources (see Resource Limits)
2. Use SSD storage for downloads directory
3. Optimize network for faster downloads
4. Monitor container health:

   docker inspect --format='{{.State.Health.Status}}' bdfr-web-interface
   

Support

For issues specific to:

• Docker setup: Check this guide and Docker logs
• BDFR functionality: See main README.md
• Web interface: See web_interface/README.md

Additional Resources

• BDFR Documentation
• Docker Documentation
• Docker Compose Documentation
• Reddit API Documentation