$ show IAmStoxe/wirehole
WireHole is a Docker Compose project that combines WireGuard, Pi-hole, and Unbound to create a private VPN with ad-blocking and recursive DNS resolution. It is not a software library but an infrastructure deployment template. The stack provides a VPN server, DNS filtering through Pi-hole, and private DNS resolution via Unbound, all running in containers. The project is designed for easy deployment on a Linux server, with a focus on security (e.g., web interfaces bound to localhost, minimal container capabilities, strong password generation). It supports two VPN backends: wg-easy (with a web UI) and linuxserver/wireguard (configuration-file based). The codebase consists of shell scripts for setup, migration, and diagnostics, along with CI/CD pipelines, test suites, and detailed documentation. The project demonstrates high operational maturity with comprehensive tests, pinning of image versions, and a doctor script for troubleshooting. While it is not a reusable software library, its scripts and configuration patterns are well-crafted and could serve as templates for similar Docker Compose deployments.
The LLM identified 3 files worth highlighting for reuse:
A self-contained Bash script that copies .env.example to .env, generates strong random passwords using openssl or /dev/urandom, retrieves the public IP via ipify, and sets file permissions. It is parameterized with --force, uses set -euo pipefail, and outputs clear next steps. Can be extracted and reused for any Docker Compose project that needs automated secret generation.
A read-only diagnostic script that checks Docker, containers, DNS chain, ports, firewall, VPN connectivity, and client handshakes. It provides color-coded output with specific fix commands for each problem. The script is modular, uses helper functions, and supports --phone for local testing. Its pattern of verifying system state and offering actionable advice is reusable for any infrastructure project.
A comprehensive end-to-end test that starts a full stack in a temporary directory, creates real WireGuard clients, and verifies handshake, traffic, DNS, and ad blocking. It tests both backends, client removal, and network paths (Docker gateway, local network, remote host). The script is isolated, idempotent, and uses temporary directories/ports to avoid interference. Its testing patterns (multi-client, connection from host network, remote SSH client) are exemplary for testing VPN stacks.