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
    • Running behind a VPN
  • 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. Item pages that say "Download unavailable … maintenance" are recognised too, so affected files are logged to session.log for retry even when the status page itself is down.
• 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.13.2 — September 2026

• Maintenance pages recognised: Bunkr answers HTTP 200 with a "Download unavailable … server under maintenance" page for files whose host is down. Those items are now logged to session.log as [MAINTENANCE] entries for later retry, raise the structured maintenance event in the web UI, and follow the backoff/skip strategy (re-fetching the item page after each delay) instead of vanishing as a generic "could not resolve" failure. Works even when status.bunkr.ru itself is down.
• MAINTENANCE_BACKOFF_DELAYS_SECONDS: the 2/5/10-minute maintenance retry waits are now an env knob (default 120,300,600, each clamped 1–3600), shared by the CDN-failure and item-page paths.

v0.13.1 — September 2026

• Quieter status-page failures: a slow or down status.bunkr.ru now logs one warning line instead of a full traceback per attempt; the fetch timeout is the new STATUS_PAGE_TIMEOUT_SECONDS knob (default 10, clamped 1–60).
• API_PORT is the real listen port: the container now starts uvicorn on API_PORT (default 8000) instead of a hard-coded 8000, and both compose files map API_PORT:API_PORT. Needed for running the app inside a VPN sidecar's network namespace, where the port must not collide with the sidecar's own services.

v0.13.0 — September 2026

• Run behind a VPN: new docker-compose.vpn.yml runs the app through a gluetun sidecar on Surfshark WireGuard with a kill switch, keeping the dashboard reachable on the LAN. Includes Synology DSM 7 Container Manager notes. See Running behind a VPN.

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	Port the app listens on inside the container and the host port compose publishes (they are kept equal).	8000
API_HOST	Address uvicorn binds to inside the container.	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
STATUS_PAGE_TIMEOUT_SECONDS 🆕	Seconds to wait for the Bunkr status page on job start and failure re-checks (clamped 1–60). A failed fetch is logged as a single warning and the job continues without host data.	10
MAINTENANCE_RETRY_STRATEGY 🆕	Strategy for maintenance: backoff (retry with delays) or skip (log and skip).	backoff
MAINTENANCE_BACKOFF_DELAYS_SECONDS 🆕	Comma-separated waits between maintenance retries, one per retry, each clamped 1–3600.	120,300,600
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.

Running behind a VPN

The README's advice to use a VPN can be baked into the stack: docker-compose.vpn.yml runs the app behind a gluetun sidecar connected to Surfshark over WireGuard. Every byte the downloader sends leaves through the tunnel, gluetun's firewall acts as a kill switch if the VPN drops, and the web UI stays reachable on your LAN.

Use the file on its own (it is not an override of docker-compose.yml):

docker compose -f docker-compose.vpn.yml up -d

1. Get WireGuard credentials from Surfshark: in your account go to VPN → Manual setup → Desktop or mobile → WireGuard, choose I don't have a keypair, generate one and copy the private key. Download a config file for any location and copy its Address line (e.g. 10.64.222.21/16); it is the same for every server.
2. Put them in .env as WIREGUARD_PRIVATE_KEY and WIREGUARD_ADDRESSES. Optionally set VPN_SERVER_COUNTRIES (default Netherlands) and TZ.
3. Start with the command above, then confirm the tunnel: docker exec bunkr wget -qO- https://api.ipify.org should print a Surfshark address, and http://<host>:${API_PORT} should serve the dashboard.

Variable	Description	Default
WIREGUARD_PRIVATE_KEY	Surfshark WireGuard private key (required).	(unset)
WIREGUARD_ADDRESSES	The Address from a Surfshark WireGuard config (required).	(unset)
VPN_SERVER_COUNTRIES	Exit country, passed to gluetun SERVER_COUNTRIES.	Netherlands
WIREGUARD_IMPLEMENTATION	auto, kernelspace or userspace. auto falls back to userspace where the kernel has no WireGuard module.	auto
WIREGUARD_GSO	Set to off if gluetun logs write /dev/net/tun: invalid argument (some NAS kernels).	on

Synology DSM 7 (Container Manager): create a Project, paste docker-compose.vpn.yml as the compose file and add the .env next to it. Set UID/GID to your DSM user (see id <user> over SSH) and point DOWNLOADS_DIR/LOGS_DIR at shared-folder paths such as /volume1/Bunkr-Downloads. The DSM kernel has no WireGuard module, so gluetun uses its userspace implementation automatically. If gluetun fails with /dev/net/tun missing, load the module once over SSH with sudo insmod /lib/modules/tun.ko and start the project again.

The bunkr service in docker-compose.vpn.yml mirrors the one in docker-compose.yml; when the base file changes, update both. Because both containers share one network namespace, gluetun's control server is moved from its default :8000 to 127.0.0.1:8001 so it does not collide with the app; if you edit the file by hand, keep that line.

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