Skip to content

Commit 767daf2

Browse files
SlykeSlyke
authored
Merge pull request #792 from Paraphraser/20250316-adguardhome-master
2025-03-16 AdGuard Home - master branch - PR 1 of 2
2 parents c2843fc + 25b5e4b commit 767daf2

File tree

2 files changed

+151
-50
lines changed

2 files changed

+151
-50
lines changed

‎.templates/adguardhome/service.yml

Lines changed: 14 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,21 @@ adguardhome:
44
restart: unless-stopped
55
environment:
66
- TZ=${TZ:-Etc/UTC}
7-
# enable host mode to activate DHCP server on ports 67/udp & 68/tcp+udp
8-
# note that you must also disable all other ports if you enable host mode
9-
# network_mode: host
7+
x-network_mode: host # see IOTstack documentation
108
ports:
11-
# regular DNS
12-
- "53:53/tcp"
13-
- "53:53/udp"
14-
# administration port (http)
15-
# note: external and internal ports MUST be the same
16-
# not active until defined via setup port
17-
- "8089:8089/tcp"
18-
# HTTPS/DNS-over-HTTPS
19-
# - "443:443/tcp"
20-
# DNS-over-QUIC
21-
# - "784:784/udp"
22-
# DNS-over-TLS
23-
# - "853:853/tcp"
24-
# setup (http)
25-
# note: only active until port 8089 becomes active
26-
- "3001:3000/tcp"
27-
# DNSCrypt
28-
# - "5443:5443/tcp"
29-
# - "5443:5443/udp"
9+
- "53:53/tcp" # regular DNS
10+
- "53:53/udp" # regular DNS
11+
- "3001:3000/tcp" # only active until port 8089 becomes active
12+
- "8089:8089/tcp" # regular administrative interface
13+
# - "443:443/tcp" # HTTPS/DNS-over-HTTPS
14+
# - "784:784/udp" # DNS-over-QUIC
15+
# - "853:853/tcp" # DNS-over-TLS
16+
# - "5443:5443/tcp" # DNSCrypt
17+
# - "5443:5443/udp" # DNSCrypt
18+
# - "6060:6060/tcp" # debugging profiles
19+
# - "67:67/udp" # DHCP service (host mode)
20+
# - "68:68/tcp" # DHCP service (host mode)
21+
# - "68:68/udp" # DHCP service (host mode)
3022
volumes:
3123
- ./volumes/adguardhome/workdir:/opt/adguardhome/work
3224
- ./volumes/adguardhome/confdir:/opt/adguardhome/conf
33-

‎docs/Containers/AdGuardHome.md

Lines changed: 137 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -4,72 +4,182 @@
44

55
* [AdGuard Home GitHub](https://github.com/AdguardTeam/AdGuardHome)
66
* [AdGuard Home DockerHub](https://hub.docker.com/r/adguard/adguardhome)
7+
* [AdGuard Home Wiki](https://adguard-dns.io/kb/adguard-home/overview/)
78

89
## Either *AdGuard Home* or *PiHole*, but not both
910

1011
AdGuard Home and PiHole perform similar functions. They use the same ports so you can **not** run both at the same time. You must choose one or the other.
1112

13+
## Service Definition { #serviceDef }
14+
15+
This is the service definition that gets added to your `docker-compose.yml` when you choose AdGuard Home.
16+
17+
``` yaml linenums="1"
18+
adguardhome:
19+
container_name: adguardhome
20+
image: adguard/adguardhome
21+
restart: unless-stopped
22+
environment:
23+
- TZ=${TZ:-Etc/UTC}
24+
x-network_mode: host # see IOTstack documentation
25+
ports:
26+
- "53:53/tcp" # regular DNS
27+
- "53:53/udp" # regular DNS
28+
- "3001:3000/tcp" # only active until port 8089 becomes active
29+
- "8089:8089/tcp" # regular administrative interface
30+
# - "443:443/tcp" # HTTPS/DNS-over-HTTPS
31+
# - "784:784/udp" # DNS-over-QUIC
32+
# - "853:853/tcp" # DNS-over-TLS
33+
# - "5443:5443/tcp" # DNSCrypt
34+
# - "5443:5443/udp" # DNSCrypt
35+
# - "6060:6060/tcp" # debugging profiles
36+
# - "67:67/udp" # DHCP service (host mode)
37+
# - "68:68/tcp" # DHCP service (host mode)
38+
# - "68:68/udp" # DHCP service (host mode)
39+
volumes:
40+
- ./volumes/adguardhome/workdir:/opt/adguardhome/work
41+
- ./volumes/adguardhome/confdir:/opt/adguardhome/conf
42+
```
43+
1244
## Quick Start { #quickStart }
1345
1446
When you first install AdGuard Home:
1547
16-
1. Use a web browser to connect to it using port 3001. For example:
48+
1. Use a web browser to connect to your Raspberry Pi on port 3001. For example:
1749
1850
```
1951
http://raspberrypi.local:3001
2052
```
53+
54+
See also [About port 3001](#about3001).
55+
56+
2. Click <kbd>Get Started</kbd>&nbsp;.
57+
3. At Step 2/5:
58+
59+
- change the port number of the administrative interface to 8089;
60+
- leave other settings at their defaults; and
61+
- click <kbd>Next</kbd>&nbsp;.
2162

22-
2. Click "Getting Started".
63+
4. Enter a username and password and click <kbd>Next</kbd>&nbsp;.
2364

24-
3. Change the port number for the Admin Web Interface to be "8089". Leave the other settings on the page at their defaults and click "Next".
25-
4. Enter a username and password and click "Next".
26-
5. Click "Open Dashboard". This redirects to port 8089.
27-
6. After the initial setup, you connect to AdGuard Home via port 8089:
65+
If you prefer to run AdGuardHome without any login credentials you can [set that up later](#nopassword) but, for now, you must choose a username and reasonably strong password.
66+
67+
5. Read the "Step 4/5" panel and click <kbd>Next</kbd>&nbsp;.
68+
6. Click <kbd>Open Dashboard</kbd>&nbsp;. This redirects to port 8089.
69+
7. After the initial setup, you connect to AdGuard Home via port 8089:
2870

2971
```
3072
http://raspberrypi.local:8089
3173
```
3274

33-
## About port 8089
75+
See also [About port 8089](#about8089).
3476

35-
Port 8089 is the default administrative user interface for AdGuard Home running under IOTstack.
77+
## About port 3001 { #about3001 }
3678

37-
Port 8089 is not active until you have completed the [Quick Start](#quickStart) procedure. You must start by connecting to port 3001.
79+
Port 3001 (external, 3000 internal) is only used during [Quick Start](#quickStart) procedure. Once port 8089 becomes active, port 3001 ceases to be active. However, you need to keep port 3001 *reserved* even though it is only ever used to set up port 8089.
3880

39-
Because of AdGuard Home limitations, you must take special precautions if you decide to change to a different port number:
81+
If you make a mess of things and need to go back to the point where port 3001 is active, you must start from a [Clean slate](#cleanSlate).
4082

41-
1. The internal and external ports **must** be the same; and
83+
## About port 8089 { #about8089 }
4284

43-
2. You **must** convince AdGuard Home that it is a first-time installation:
85+
Port 8089 (external and internal) is the administrative user interface for AdGuard Home running under IOTstack.
4486

45-
```console
46-
$ cd ~/IOTstack
47-
$ docker-compose stop adguardhome
48-
$ docker-compose rm -f adguardhome
49-
$ sudo rm -rf ./volumes/adguardhome
50-
$ docker-compose up -d adguardhome
87+
Port 8089 is not active until you have completed the [Quick Start](#quickStart) procedure. You must start by connecting to port 3001.
88+
89+
Because of AdGuard Home limitations, you must take special precautions if you decide to change the administrative interface to a different port number:
90+
91+
1. The internal and external ports **must** be the same (see line 12 in the [service definition](#serviceDef). For example, to use port 9999 instead of port 8089, change the service definition like this:
92+
93+
``` yaml linenums="12"
94+
- "9999:9999/tcp" # regular administrative interface
5195
```
5296

53-
3. Repeat the [Quick Start](#quickStart) procedure, this time substituting the new Admin Web Interface port where you see "8089".
97+
2. You must start from a [Clean slate](#cleanSlate).
98+
99+
3. When you repeat the [Quick Start](#quickStart) procedure, substitute your new Admin Web Interface port (eg "9999") where you see "8089".
54100

55-
## About port 3001:3000
101+
## Clean slate { #cleanSlate }
56102

57-
Port 3001 (external, 3000 internal) is only used during [Quick Start](#quickStart) procedure. Once port 8089 becomes active, port 3001 ceases to be active.
103+
To start over from a clean slate, proceed like this:
58104

59-
In other words, you need to keep port 3001 reserved even though it is only ever used to set up port 8089.
105+
``` console
106+
$ cd ~/IOTstack
107+
$ docker-compose down adguardhome
108+
$ sudo rm -rf ./volumes/adguardhome
109+
$ docker-compose up -d adguardhome
110+
```
111+
112+
The container will go into "first run" mode and port 3001 will become active. You can then follow the [Quick Start](#quickStart) procedure.
60113

61114
## About Host Mode
62115

63-
If you want to run AdGuard Home as your DHCP server, you need to put the container into "host mode". You need edit the AdGuard Home service definition in `docker-compose.yml` to:
116+
If you want to run AdGuard Home as your DHCP server, you need to put the container into "host mode". The line numbers in this section refer to those in the [service definition](#serviceDef) above.
117+
118+
You need to make two changes:
64119

65-
1. add the line:
120+
1. Remove the `x-` prefix from line 7 so that it looks like:
66121

67-
```yaml
68-
network_mode: host
122+
``` yaml linenums="7"
123+
network_mode: host # see IOTstack documentation
69124
```
125+
126+
Removing the `x-` prefix has the effect of activating the `network_mode:` clause.
127+
128+
2. Add an `x-` prefix to line 8 so that it looks like:
129+
130+
``` yaml linenums="8"
131+
x-ports:
132+
```
133+
134+
Inserting the `x-` prefix has the effect of deactivating the entire `ports:` clause.
135+
136+
Save your work. To apply the changes:
70137

71-
2. remove the `ports:` directive and **all** of the port mappings.
138+
```
139+
$ cd ~/IOTstack
140+
$ docker-compose up -d adguardhome
141+
```
142+
143+
When you run the container in host mode, **all** of the *internal* (right hand side) ports listed in the [`ports:` clause](#serviceDef) become active. If you are running *other* services on your host that are already bound to one or more of those ports, Docker will refuse to start the container. It is up to you to resolve those port conflicts.
72144

73145
Note:
74146

75147
* It is not really a good idea to offer DHCP services from a container. This is because containers generally start far too late in a boot process to be useful. If you want to use AdGuard Home for DHCP, you should probably consider a native installation.
148+
149+
## Passwordless administration { #nopassword }
150+
151+
In many home networks, requirements for strong login credentials on every service can be overkill. If it's appropriate for your situation you can choose to run AdGuardHome "passwordless" like this:
152+
153+
1. Use `sudo` to open the following file in a text editor:
154+
155+
```
156+
~/IOTstack/volumes/adguardhome/confdir/AdGuardHome.yaml
157+
```
158+
159+
For example:
160+
161+
``` console
162+
$ cd ~/IOTstack
163+
$ sudo vi ./volumes/adguardhome/confdir/AdGuardHome.yaml
164+
```
165+
166+
2. Find these lines:
167+
168+
``` yaml
169+
users:
170+
- name: «username»
171+
password: «hashCode»
172+
```
173+
174+
3. Replace those three lines with this single line:
175+
176+
``` yaml
177+
users: []
178+
```
179+
180+
4. Save your work.
181+
5. Restart the container:
182+
183+
``` console
184+
$ docker-compose restart adguardhome
185+
```

0 commit comments

Comments
 (0)