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):
   ```bash
   git clone <repository-url>
   cd BDFR_Web
   ```

2. **Create required directories**:
   ```bash
   mkdir -p downloads data config
   ```

3. **Configure environment variables** (optional but recommended):
   ```bash
   cp web_interface/.env.example .env
   # Edit .env with your Reddit OAuth credentials
   ```

4. **Start the container**:
   ```bash
   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:

```env
# 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:**
```bash
docker-compose up -d
```

**Stop the container:**
```bash
docker-compose down
```

**View logs:**
```bash
docker-compose logs -f
```

**Restart the container:**
```bash
docker-compose restart
```

**Rebuild after code changes:**
```bash
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:**
```bash
docker exec -it bdfr-web-interface bash
```

**Run BDFR commands:**
```bash
# 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:**
```bash
# 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`](docker-compose.yml:11):

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

Or set the PORT environment variable:
```env
PORT=3000
```

### Custom Download Directory

Mount a different host directory for downloads:

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

```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`](docker-compose.yml):

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

## Troubleshooting

### Container Won't Start

**Check logs:**
```bash
docker-compose logs bdfr-web
```

**Verify ports aren't in use:**
```bash
# Windows
netstat -ano | findstr :8000

# Linux/Mac
lsof -i :8000
```

**Rebuild the image:**
```bash
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:

```bash
# 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:
```bash
docker-compose down
docker-compose up -d
```

**Solution 2: Fix Host Directory Permissions**

**Linux/Mac:**
```bash
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:
   ```bash
   docker inspect bdfr-web-interface | grep -A 10 Mounts
   ```

2. Verify download directory inside container:
   ```bash
   docker exec bdfr-web-interface ls -la /app/downloads
   ```

3. Check container logs for errors:
   ```bash
   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:
   ```bash
   docker exec bdfr-web-interface ls -la /app/data/bdfr-config
   ```

2. Check environment variables are set correctly:
   ```bash
   docker exec bdfr-web-interface env | grep BDFR
   ```

3. If the directory doesn't exist or has wrong permissions:
   ```bash
   docker-compose down
   docker-compose up -d --build
   ```

### OAuth Authentication Issues

1. Verify credentials in `.env` or [`docker-compose.yml`](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:
   ```bash
   docker-compose restart
   ```

### High Memory Usage

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

1. Monitor memory usage:
   ```bash
   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:
   ```bash
   docker ps | grep bdfr
   ```

2. Stop all instances and restart:
   ```bash
   docker-compose down
   docker-compose up -d
   ```

## Maintenance

### Backing Up Data

**Backup downloads and database:**
```bash
# 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):
```bash
#!/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:**
```bash
git pull origin main
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

**Update only Docker image:**
```bash
docker-compose pull
docker-compose up -d
```

### Cleaning Up

**Remove stopped containers:**
```bash
docker-compose down
```

**Remove containers and volumes:**
```bash
docker-compose down -v
```

**Remove images:**
```bash
docker-compose down --rmi all
```

**Full cleanup (including downloads):**
```bash
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

```nginx
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:**
```bash
DOCKER_BUILDKIT=1 docker-compose build
```

**Multi-stage build** is already implemented in the [`Dockerfile`](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**:
   ```bash
   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](README.md)
- **Web interface**: See [web_interface/README.md](web_interface/README.md)

## Additional Resources

- [BDFR Documentation](README.md)
- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose Documentation](https://docs.docker.com/compose/)
- [Reddit API Documentation](https://www.reddit.com/dev/api)