BunkrDownloader

Rich CLI + web dashboard for grabbing albums and files from Bunkr with resilient retries, live progress, and container-ready deployment.

If you find this project useful, please consider giving it a star on GitHub! ⭐

Table of Contents

• BunkrDownloader
  • Table of Contents
  • Highlights
  • Latest Release Updates
  • Quick Start
    • With Docker Compose (recommended)
      • Common Operations
      • Environment Variables
    • Local runtime
  • CLI Usage
  • Web Dashboard
  • Configuration
  • Architecture
  • Development
  • Contributing
  • Support & Issues
  • Forked credits
  • License
  • Star History

Highlights

• Dual experience: Python CLI (downloader.py, main.py) or a polished web dashboard powered by FastAPI.
• Liquid-glass UI 🆕: macOS Sonoma / iOS 17 aesthetic with backdrop-filter vibrancy, OKLCH-based color tokens, an Auto / Light / Dark appearance menu that follows your OS, and WCAG-AA contrast in both modes.
• Realtime feedback: Rich terminal UI and a websocket + polling hybrid on the web keep progress/logs alive, even after restarts.
• Concurrent + reliable 🆕: Per-job network context isolates parallel downloads; monotonic event IDs with a WS ↔ polling mutex prevent duplicate or missed progress updates across reconnects; progress bars converge to 100% (no more 99% stalls); sandboxed download root, bounded in-memory event log, optional bearer-token auth, and TTL-scoped job reaper keep long-running containers safe.
• Maintenance detection 🆕: Real-time status page checks detect server maintenance and apply intelligent retry strategies with longer delays or skip affected files.
• Smart filtering: Include/ignore rules, disk-space guard, filename sanitisation, and album pagination handled automatically.
• Configurable storage: Point downloads to any folder (CLI --custom-path or web directory picker) with existing files skipped safely.
• Container friendly: Multi-stage Docker image, docker-compose stack, and CI pipeline for publishing multi-arch images to GHCR.

Note/Advice: Use a VPN. Bunkr sometimes blocks your IP when you bulk download. While it gets unblocked after a while, its best to use this behind a VPN

Latest Release Updates

v0.12.0 — June 2026

• Update notifications in the web UI: the dashboard now checks GitHub for newer releases and shows an "↑ update available: vX.Y.Z" badge directly under the version when your running build is out of date, linking straight to the Releases page.
• Light on GitHub: the check runs server-side and is cached (~6h), so all browser sessions share a single upstream request instead of each polling GitHub — and a GitHub hiccup simply shows no badge rather than erroring.

v0.11.5 — June 2026

• Security maintenance: cleared the open frontend security advisories — axios bumped to 1.16.1 (GHSA-654m-c8p4-x5fp, Proxy-Authorization header injection via prototype pollution) and the build-time postcss to 8.5.15 (GHSA-qx2v-qp2m-jg93, CSS-stringify XSS). npm audit now reports zero vulnerabilities.

v0.11.4 — June 2026

• Downloads work again: Bunkr retired the /api/vs endpoint (it now returns 404 for every file) and switched to signed CDN URLs — item pages embed the raw CDN link plus a signing endpoint that issues a short-lived access token. The crawler was rewritten to follow this new flow, restoring album and single-file downloads.
• SSRF hardening: the signing endpoint host is read from page content, so it is now validated (HTTPS + host allowlist) before any server-side request is made. Override the allowlist with BUNKR_SIGN_ALLOWED_HOSTS (default cdn.cr) if Bunkr rotates its signing infrastructure.

See the Releases page for the full changelog.

Quick Start

With Docker Compose (recommended)

This is the easiest way to run BunkrDownloader. You'll need Docker Desktop installed on your machine (or Docker Engine + Compose on Linux).

1. Prepare configuration: Create a .env file to customize your settings.

   cp .env.sample .env

   Windows users: You can copy and rename the file in File Explorer.

2. Customize (Optional): Open .env in a text editor to change where files are saved (DOWNLOADS_DIR) or which port to use (API_PORT).

3. Start the application: Run the following command to download the image and start the service in the background:

   docker compose up -d

   Once running, open http://localhost:8000 in your browser.

Common Operations

• Stop: docker compose down
• Updates: Run docker compose pull followed by docker compose up -d to switch to the latest version.
• Logs: docker compose logs -f (Ctrl+C to exit).

Environment Variables

You can configure the deployment by setting the following environment variables in your .env file.

Variable	Description	Default Value
API_PORT	The host port to access the Web UI and API.	8000
API_HOST	The host address the application listens on.	0.0.0.0
DOWNLOADS_DIR	The local directory where files will be saved.	./Downloads
LOGS_DIR	The local directory where logs will be stored.	./logs
SESSION_LOG_PATH	The internal path for the session log.	/app/logs/session.log
IMAGE_TAG	The Docker image version tag to use (e.g., latest or 1.2.3).	latest
UID	The user ID to run the container as.	1000
GID	The group ID to run the container as.	1000
STATUS_CHECK_ON_FAILURE 🆕	Enable real-time status page checks on download failures.	true
STATUS_CACHE_TTL_SECONDS 🆕	Cache duration for status page results in seconds.	60
MAINTENANCE_RETRY_STRATEGY 🆕	Strategy for maintenance: backoff (retry with delays) or skip (log and skip).	backoff
ALLOWED_DOWNLOAD_ROOT 🆕	Filesystem root that incoming custom_path and /api/directories?basePath values must resolve under. Rejects any path that escapes this root with HTTP 422. Set to / to disable sandboxing (not recommended for public-facing deployments).	<cwd>/Downloads
API_ACCESS_TOKEN 🆕	Shared bearer token. When set, every /api/* request must carry Authorization: Bearer <token> and every /ws/* connection must include ?token=<token>. When unset, the API is unauthenticated and a warning is logged on startup — safe only on a trusted LAN.	(unset)
ALLOWED_ORIGINS 🆕	Comma-separated list of CORS-allowed origins (e.g. https://dash.example.com,https://admin.example.com). Takes precedence over ALLOWED_ORIGIN_REGEX when set.	(unset)
ALLOWED_ORIGIN_REGEX 🆕	Regex fallback for CORS when ALLOWED_ORIGINS is unset. The default covers Vite dev-server and uvicorn on localhost.	https?://(localhost|127\.0\.0\.1)(:\d+)?
JOB_EVENT_RETENTION 🆕	Maximum number of events retained per job in the in-memory ring buffer. Clients whose cursor falls below the retained floor get a 410 Gone so they can reset rather than silently missing history.	2000
JOB_TTL_HOURS 🆕	Terminal jobs (completed / failed / cancelled) older than this are evicted by the background reaper so long-running containers don't grow unbounded.	24
JOB_REAPER_INTERVAL_SECONDS 🆕	How often the reaper scans for stale terminal jobs.	900
BUNKR_SIGN_ALLOWED_HOSTS 🆕	Comma-separated allowlist of hosts the page-declared media signing endpoint may use (SSRF guard). A candidate matches when it equals an entry or is a subdomain of one, and only HTTPS is accepted. Override when Bunkr rotates its signing infrastructure off cdn.cr.	cdn.cr

Set IMAGE_TAG to a published semantic version (for example 1.2.3) if you want to pin a specific release; otherwise latest is used.

Local runtime

# Backend
pip install -r requirements.txt
uvicorn src.web.app:app --reload

# Frontend (optional live dev server)
cd frontend
npm install
npm run dev

The Vite dev server proxies API/WebSocket traffic to http://localhost:8000 by default. Run npm run build once to bake a production bundle served by FastAPI.

CLI Usage

# Single URL
python3 downloader.py <bunkr_url> [--include term ...] [--ignore term ...] [--custom-path /path] [--disable-ui] [--disable-disk-check] [--skip-status-check] [--maintenance-strategy backoff|skip] [--status-cache-ttl SECONDS]

# Batch mode (URLs.txt)
python3 main.py [shared flags]

• --include downloads files containing any supplied substring.
• --ignore skips files containing any supplied substring.
• --custom-path points downloads to <path>/Downloads.
• --disable-ui swaps the Rich interface for plain logging (useful in notebooks/CI).
• --skip-status-check 🆕 disables real-time status page checks on download failures (defaults to enabled).
• --status-cache-ttl SECONDS 🆕 controls cache duration for status page results (default: 60s).
• --maintenance-strategy backoff|skip 🆕 chooses retry behavior: backoff retries with longer delays (2min, 5min, 10min), skip logs and skips maintenance files.

Web Dashboard

• Job launcher – paste URLs, set filters, toggle the disk check, or choose a custom destination via the directory browser.
• Progress panes – overall progress + per-file stripes; tooltips explain each control and metric.
• Live log – chronological events, retries, and skips with full timestamps.
• Resilient updates – when a WebSocket drops (e.g. container restart) the UI polls /api/downloads/{job}/events until the socket reconnects.
• Source shortcut – in-app link to the GitHub repository for quick reference.
• Version badge – header shows the semantic version embedded in the running container image.

Configuration

• .env (tracked example) controls container defaults: API_HOST, API_PORT, DOWNLOADS_DIR, plus Vite proxy hints (VITE_*).
• Web UI tooltips describe every form element; hover to see accepted formats and side effects.
• Downloads default to Downloads/ in the working directory unless custom_path (CLI) or the directory picker overrides it.
• session.log persists problematic URLs so you can retry them later. 🆕 Maintenance events are logged with format: [MAINTENANCE] timestamp | subdomain | status | url.

Architecture

• downloader.py / main.py call validate_and_download, which builds a SessionInfo and streams progress via LiveManager.
• src/web/app.py wraps the same flow: JobEventBroker buffers events, WebLiveManager mirrors CLI progress/log calls, and FastAPI exposes REST + WebSocket endpoints.
• src/crawlers/* resolve album pagination, decrypt media URLs, and normalise filenames.
• src/downloaders/* handle concurrency, retries, and chunked writes through download_utils.save_file_with_progress; subdomain outages are tracked with bunkr_utils.
• 🆕 Maintenance detection: bunkr_utils.refresh_server_status checks Bunkr's status page on download failures with TTL-based caching. Failed downloads are grouped by subdomain and rechecked before final retries.
• frontend/src/App.jsx consumes /api/downloads, /api/directories, /ws/jobs/{id}, and the /api/downloads/{id}/events polling fallback for seamless updates. 🆕 Maintenance events trigger toast notifications.

Development

• Python ≥ 3.10, Node ≥ 18 recommended.
• Activate the virtualenv and lint with python -m pylint $(git ls-files '*.py'); resolve any findings before committing.
• Run python -m compileall src and npm run build before opening a PR to catch syntax/bundle issues.
• docker compose up --build exercises the full stack locally using the tracked .env.
• Use session.log and the web log pane to inspect failed URLs or storage issues.

Contributing

• Start with the guidelines in CONTRIBUTING.md for branching, linting, and smoke-test expectations.
• Prefer Conventional Commits (feat:, fix:, docs:, etc.) so semantic-release can generate changelogs correctly.
• Include the manual checks you ran (lint, compileall, npm run build, CLI/Web smoke tests) in your pull request description.
• Keep your branch rebased on main and respond quickly to review feedback to keep the release pipeline flowing.

Support & Issues

• Open a new issue from the repository’s Issues → New issue page; choose the Bug report template for defects or the Feature request template for enhancements.
• The templates collect environment details (OS, Python version, tool version) and walk you through logs, reproduction steps, and desired outcomes so maintainers can triage quickly.
• Always confirm you’re running the latest release from GitHub Releases and search for duplicates before filing.
• Blank issues are disabled, so pick the template that’s closest to your situation and use the “Additional context” field to capture anything extra.

Forked credits

This project is a fork of Lysagxra/BunkrDownloader. However, it has been heavily refactored and modified for a web dashboard interface and other enhancements including dockerizing the application.

License

MIT License © tekgnosis-net

Star History