Skip to content

Commit f948d90

Browse files
IAmStoxeIAmStoxe
authored
Merge pull request #137 from IAmStoxe/modernize
Modernize the stack: Pi-hole v6, maintained images, hardened defaults
2 parents 1eed5a5 + 4c2fb2e commit f948d90

28 files changed

Lines changed: 5021 additions & 517 deletions

‎.env.example‎

Lines changed: 166 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,175 @@
1-
# Docker Compose Environment Configuration
1+
# WireHole configuration
2+
#
3+
# HOW TO USE THIS FILE:
4+
# 1. Copy this file to ".env" with the command: cp .env.example .env
5+
# 2. Set a value for each variable that has the mark "REQUIRED".
6+
# 3. Keep the file ".env" secret. It holds your passwords.
7+
# Git ignores the file ".env".
8+
#
9+
# Every other variable has a default value. Remove the comment character "#"
10+
# to change a default value.
11+
#
12+
# Make a strong password with this command:
13+
# openssl rand -base64 24
14+
# Or use the helper script:
15+
# ./scripts/generate-secrets.sh
216

3-
# General settings
4-
# Set your timezone
5-
TIMEZONE=America/Los_Angeles
17+
# ===========================================================================
18+
# REQUIRED SETTINGS
19+
# ===========================================================================
620

7-
# User and group identifiers
8-
# User ID
21+
# REQUIRED: The public address of your server. Your VPN clients connect to
22+
# this address. Use a public IP address or a domain name.
23+
# Find your public IP address with this command: curl -s ifconfig.me
24+
# Use your dynamic DNS name here if your IP address changes.
25+
# Example: VPN_HOST=vpn.example.com
26+
VPN_HOST=
27+
28+
# REQUIRED: The password of the Pi-hole web interface.
29+
PIHOLE_PASSWORD=
30+
31+
# REQUIRED: the password of the VPN web interface.
32+
# Set this value even if you use the profile "wireguard". Docker Compose reads
33+
# every service in the file, so the stack does not start without it.
34+
# wg-easy reads this password one time only, at the first start.
35+
# Change the password later in the web interface.
36+
WG_EASY_PASSWORD=
37+
38+
# ===========================================================================
39+
# VPN BACK END
40+
# ===========================================================================
41+
42+
# Select the VPN back end.
43+
# wg-easy = a VPN server with a web interface. This is the default.
44+
# wireguard = a VPN server with configuration files and QR codes only.
45+
# Use one value only. Two VPN servers cannot use the same port.
46+
COMPOSE_PROFILES=wg-easy
47+
48+
# The public UDP port of the VPN. Open this port on your firewall and on
49+
# your router.
50+
VPN_PORT=51820
51+
52+
# The networks that a client sends through the VPN.
53+
# "0.0.0.0/0, ::/0" is a full tunnel. The client sends all traffic. The
54+
# client gets ad blocking for all traffic.
55+
# "10.2.0.0/24" is a split tunnel. The client sends only the DNS traffic
56+
# and the web interfaces. All other traffic does not use the VPN.
57+
VPN_ALLOWED_IPS=0.0.0.0/0, ::/0
58+
59+
# --- Settings of the profile "wg-easy" -------------------------------------
60+
61+
# The user name of the VPN web interface.
62+
WG_EASY_USERNAME=admin
63+
64+
# The network of the VPN clients.
65+
VPN_SUBNET=10.8.0.0/24
66+
67+
# This stack carries IPv4 only. wg-easy gives the clients no IPv6 address.
68+
# The value "::/0" in VPN_ALLOWED_IPS still stops IPv6 leaks. It sends IPv6
69+
# traffic into the tunnel, where it stops, instead of around the tunnel.
70+
71+
# Permit HTTP for the web interface. Set the value "false" if you use a
72+
# reverse proxy with TLS. Read the file SECURITY.md.
73+
WG_EASY_INSECURE=true
74+
75+
# --- Settings of the profile "wireguard" -----------------------------------
76+
77+
# The number of clients, or a list of client names.
78+
# Example of a number: WIREGUARD_PEERS=3
79+
# Example of a list: WIREGUARD_PEERS=phone,laptop,tablet
80+
# An empty value uses an existing server configuration without regenerating it.
81+
# The migration script uses that mode. New installations must keep a value.
82+
WIREGUARD_PEERS=1
83+
84+
# The network of the VPN clients. Give the first address of the network.
85+
WIREGUARD_INTERNAL_SUBNET=10.13.13.0
86+
87+
# Print the QR codes of the clients to the log.
88+
# SECURITY: A QR code holds a private key. Set the value "false" if other
89+
# persons can read your logs.
90+
WIREGUARD_LOG_CONFS=true
91+
92+
# ===========================================================================
93+
# WEB INTERFACES
94+
# ===========================================================================
95+
96+
# The address that publishes the web interfaces on the host.
97+
# SECURITY: The default value 127.0.0.1 is safe. Only this computer can open
98+
# the pages. Connect to the VPN to reach the pages from another computer.
99+
# The value 0.0.0.0 publishes the pages to your network and possibly to the
100+
# internet. Use a strong password before you change this value.
101+
WEB_BIND_ADDRESS=127.0.0.1
102+
103+
# The host port of the Pi-hole web interface.
104+
# Open the page at: http://127.0.0.1:8080/admin
105+
PIHOLE_WEB_PORT=8080
106+
107+
# The host port of the VPN web interface (profile "wg-easy").
108+
# Open the page at: http://127.0.0.1:51821
109+
WG_EASY_UI_PORT=51821
110+
111+
# ===========================================================================
112+
# GENERAL SETTINGS
113+
# ===========================================================================
114+
115+
# Your time zone. The logs and the statistics use this time zone.
116+
# Find your time zone in this list:
117+
# https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
118+
TZ=Etc/UTC
119+
120+
# The user ID and the group ID for the files of the profile "wireguard".
121+
# Find your values with the command: id -u && id -g
9122
PUID=1000
10-
# Group ID
11123
PGID=1000
12124

13-
# Network settings
14-
# Subnet for the private network - NOT USED IN COMPOSE FILE, CAN BE REMOVED
15-
# SUBNET=10.2.0.0/24
125+
# The restart policy of the containers.
126+
# "unless-stopped" starts the containers again after a restart of the host.
127+
RESTART_POLICY=unless-stopped
16128

17-
# Static IP for Unbound
18-
UNBOUND_IPV4_ADDRESS=10.2.0.200
19-
# Static IP for Pi-hole
129+
# The maximum size of one log file and the number of log files.
130+
LOG_MAX_SIZE=10m
131+
LOG_MAX_FILE=3
132+
133+
# ===========================================================================
134+
# NETWORK
135+
# ===========================================================================
136+
137+
# The internal Docker network of the stack.
138+
# Change these three values together. The two addresses must be inside
139+
# the subnet. Change them if another network in your system uses 10.2.0.0/24.
140+
WIREHOLE_SUBNET=10.2.0.0/24
20141
PIHOLE_IPV4_ADDRESS=10.2.0.100
21-
# Port for Wireguard server
22-
WIREGUARD_SERVER_PORT=51820
23-
# DNS for Wireguard peers, set to Pi-hole
24-
WIREGUARD_PEER_DNS=10.2.0.100
142+
UNBOUND_IPV4_ADDRESS=10.2.0.200
25143

26-
# Wireguard settings
27-
# Number of peers (clients) to generate
28-
WIREGUARD_PEERS=1
144+
# ===========================================================================
145+
# PI-HOLE
146+
# ===========================================================================
147+
148+
# The rate limit of Pi-hole. The format is "queries/seconds".
149+
# Pi-hole counts the queries of one client address. All your VPN clients
150+
# share one address. Therefore the limit of Pi-hole (1000/60) can block
151+
# normal traffic. The value "0/0" disables the limit.
152+
PIHOLE_RATE_LIMIT=0/0
153+
154+
# Write the query log. Set the value "false" for more privacy.
155+
PIHOLE_QUERY_LOGGING=true
156+
157+
# The theme of the web interface.
158+
# Values: default-auto, default-light, default-dark, default-darker,
159+
# high-contrast, high-contrast-dark, lcars
160+
PIHOLE_THEME=default-auto
161+
162+
# ===========================================================================
163+
# IMAGE VERSIONS
164+
# ===========================================================================
165+
# The stack pins each version. A pinned version gives the same result on
166+
# every computer. Read the release notes before you change a version.
167+
# Pi-hole: https://github.com/pi-hole/docker-pi-hole/releases
168+
# Unbound: https://github.com/klutchell/unbound-docker/releases
169+
# wg-easy: https://github.com/wg-easy/wg-easy/releases
170+
# WireGuard: https://github.com/linuxserver/docker-wireguard/releases
29171

30-
# Wireguard-UI settings
31-
# Session secret, change to something secure
32-
WGUI_SESSION_SECRET=
33-
# Username for Wireguard-UI
34-
WGUI_USERNAME=admin
35-
# Password for Wireguard-UI, change to something secure
36-
WGUI_PASSWORD=admin
37-
# Enable management of Wireguard start
38-
WGUI_MANAGE_START=true
39-
# Enable management of Wireguard restart
40-
WGUI_MANAGE_RESTART=true
41-
42-
# Pi-hole settings
43-
# Web password for Pi-hole, set to a secure password
44-
WEBPASSWORD=
45-
46-
# IP address for the Unbound server used by Pi-hole
47-
PIHOLE_DNS=10.2.0.200
172+
PIHOLE_VERSION=2026.07.2
173+
UNBOUND_VERSION=1.26.0
174+
WG_EASY_VERSION=15.4.0
175+
WIREGUARD_VERSION=1.0.20260223-r0-ls120

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Bug report
2+
description: The stack does not work as documented.
3+
labels: [bug]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Run `./scripts/wirehole-doctor.sh` first. It finds the common
9+
problems and prints the fix. If you upgraded from the old
10+
WireHole, read UPGRADING.md before you file.
11+
- type: textarea
12+
id: what
13+
attributes:
14+
label: What happens
15+
description: What did you do, what did you expect, what happened instead?
16+
validations:
17+
required: true
18+
- type: textarea
19+
id: doctor
20+
attributes:
21+
label: Doctor output
22+
description: Paste the output of ./scripts/wirehole-doctor.sh. Remove your public IP address.
23+
render: text
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: env
28+
attributes:
29+
label: Environment
30+
description: OS, architecture (amd64/arm64), Docker version, and which profile (wg-easy or wireguard).
31+
validations:
32+
required: true
33+
- type: textarea
34+
id: logs
35+
attributes:
36+
label: Logs
37+
description: Paste the log of the failing service (docker compose logs <service>). Remove addresses and passwords.
38+
render: text

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Security problem
4+
url: https://github.com/IAmStoxe/wirehole/security
5+
about: Do not open a public issue for a security weakness. Use private reporting.
6+
- name: Upgrade help
7+
url: https://github.com/IAmStoxe/wirehole/blob/master/UPGRADING.md
8+
about: Coming from the old WireHole layout? The upgrade guide covers the migration.

‎.github/dependabot.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Dependabot looks for new versions and opens a pull request.
2+
#
3+
# NOTE: The stack sets the image versions in the file ".env", and not in the
4+
# file "docker-compose.yml". Dependabot cannot read the file ".env".
5+
# Therefore Dependabot updates the GitHub Actions only. The workflow "CI"
6+
# runs each week and finds a problem with a new image version.
7+
# Read the file README.md for the manual update procedure.
8+
9+
version: 2
10+
updates:
11+
- package-ecosystem: github-actions
12+
directory: /
13+
schedule:
14+
interval: weekly
15+
commit-message:
16+
prefix: ci
17+
labels:
18+
- dependencies

‎.github/pull_request_template.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## What does this change?
2+
3+
<!-- One or two sentences. What was broken or missing, and why is this the right fix? -->
4+
5+
## How was it tested?
6+
7+
<!-- Paste the relevant output. "shellcheck scripts/*.sh tests/*.sh" and "./tests/e2e-vpn.sh" cover most changes. -->
8+
9+
## Checklist
10+
11+
- [ ] One change per pull request.
12+
- [ ] `.env.example` and the README match the new behavior, if it changed.
13+
- [ ] Comments and docs use short, simple sentences and plain ASCII.

0 commit comments

Comments
 (0)