feat(UI): added docker image and config
This commit is contained in:
@@ -0,0 +1,477 @@
|
||||
# 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
|
||||
# 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` | `/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 /downloads --subreddit Python -L 10
|
||||
|
||||
# Download from a user
|
||||
bdfr download /downloads --user reddituser --submitted -L 100
|
||||
|
||||
# Archive posts
|
||||
bdfr archive /downloads --subreddit all -L 500
|
||||
|
||||
# Clone (download + archive)
|
||||
bdfr clone /downloads --subreddit EarthPorn -L 50
|
||||
```
|
||||
|
||||
**One-line BDFR commands:**
|
||||
```bash
|
||||
# Download without entering the container
|
||||
docker exec bdfr-web-interface bdfr download /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:/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:
|
||||
|
||||
**Linux/Mac:**
|
||||
```bash
|
||||
sudo chown -R $USER:$USER downloads data config
|
||||
chmod -R 755 downloads data config
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
Ensure Docker Desktop has access to the drive where the project is located (Settings → Resources → File Sharing).
|
||||
|
||||
### 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 /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)
|
||||
Reference in New Issue
Block a user