Docker Deployment & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
ProxyBroker2 uses Docker to provide a portable, production-ready environment for finding, checking, and serving proxies. The Docker image encapsulates all necessary Python dependencies (Python 3.10-3.14) and system tools like upx or binutils required for advanced operations.
Sources: README.md:133-142, README.md:11-15, pyproject.toml:23-31
Image Usage and Basic Commands
The official image is hosted on Docker Hub as bluet/proxybroker2. You can pull and execute the image using standard Docker CLI commands to perform proxy discovery or start a local rotation server.
Core Commands
| Action | Command |
|---|---|
| Pull Image | docker pull bluet/proxybroker2 |
| View Help | docker run --rm bluet/proxybroker2 --help |
| Find Proxies | docker run --rm bluet/proxybroker2 find --types HTTP --limit 10 |
| Start Server | docker run --rm -p 8888:8888 bluet/proxybroker2 serve --host 0.0.0.0 --port 8888 --types HTTP |
Sources: README.md:133-142, README.md:213-215, CLAUDE.md:43-51
Build Pipeline and Infrastructure
The build process for the ProxyBroker2 Docker image supports multi-platform architectures and includes security scanning. The docker-build.sh script automates these stages.
Build Workflow
The diagram shows the sequence of events from pulling the base image to pushing multi-platform tags.
Sources: docker-build.sh:5-34
Platform and Security Specifications
The image is built using python:3.14-slim as a base and supports both linux/amd64 and linux/arm64/v8 platforms. Security is enforced through docker scout and grype scans, specifically filtering for "High" and "Critical" vulnerabilities during the build cycle.
Sources: docker-build.sh:9-10, docker-build.sh:23, CHANGELOG.md:185-186
Configuration and Volume Mounting
ProxyBroker2 features a custom provider system that allows users to add proxy sources via YAML or JSON configuration files without modifying the core source code. Docker users manage this through volume bind-mounting.
Provider Loading Logic
ProxyBroker2 automatically searches for configuration files in specific locations. The default in-container path is /configs.
- Place
*.yamlor*.jsonfiles in a local directory (e.g.,~/proxy-sources/). - Bind-mount this directory to
/configsinside the container. - The Broker loads these configurations at startup.
The diagram illustrates the flow of custom configuration files from the host machine into the ProxyBroker2 engine.
Sources: CLAUDE.md:175-188, proxybroker/provider_utils.py:448-468, CHANGELOG.md:135-151
Environment Variables and CLI Flags
You can override the default configuration directory using environment variables or CLI flags during the docker run execution.
| Parameter | Type | Description |
|---|---|---|
/configs | Default Path | The internal directory scanned for YAML/JSON files. |
--provider-dir | CLI Flag | Repeatable flag to add additional scanning paths. |
PROXYBROKER_PROVIDER_DIR | Env Var | Fallback single path if no CLI flag is provided. |
Sources: CLAUDE.md:175-188, proxybroker/provider_utils.py:461-468
Custom Provider Configuration Example
When deploying via Docker, use the following YAML structure for a custom source file:
# ~/proxy-sources/internal_list.yaml
name: Internal Source
type: simple
url: https://internal.example.com/proxies.txt
format: text
protocols: [HTTP, HTTPS]
Run the container with the mount:
docker run --rm \
-v ~/proxy-sources:/configs \
bluet/proxybroker2 \
find --types HTTP --limit 10
Sources: README.md:239-251, proxybroker/provider_utils.py:532-540
Conclusion
Docker deployment provides the most stable method for running ProxyBroker2 across different operating systems. By utilizing the /configs bind-mount, you can extend the tool's proxy discovery capabilities with private or custom sources while maintaining the isolation and reproducibility of a containerized environment.
Sources: README.md:133-142, CLAUDE.md:175-188