DNS Configuration for Tutorial Testing¶

Tutorial tests require DNS wildcard resolution to work. Each deployed application gets a unique hostname like hop3-tuto-express.hop3.dev, which must resolve to the Hop3 server IP.

Quick Setup (macOS)¶

Run the provided setup script:

# Replace <server-ip> with your Hop3 server IP
python scripts/setup-dnsmasq.py <server-ip>

This configures: - *.hop3.dev -> <server-ip> (for remote SSH testing) - *.hop3-docker.dev -> 127.0.0.1 (for Docker testing)

Manual Setup¶

Prerequisites¶

Install dnsmasq on macOS:

brew install dnsmasq

Configuration¶

Create dnsmasq config at /opt/homebrew/etc/dnsmasq.d/hop3.conf:

# Wildcard DNS for Hop3 testing
address=/hop3.dev/<server-ip>
address=/hop3-docker.dev/127.0.0.1

Configure main dnsmasq.conf at /opt/homebrew/etc/dnsmasq.conf:

# Listen on localhost
listen-address=127.0.0.1

# Include additional config files
conf-dir=/opt/homebrew/etc/dnsmasq.d/,*.conf

Create macOS resolver files:

sudo mkdir -p /etc/resolver

# For remote testing
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/hop3.dev

# For Docker testing
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/hop3-docker.dev

Start dnsmasq:

sudo dnsmasq

Verify Configuration¶

# Test wildcard resolution
dig test.hop3.dev @127.0.0.1

# Expected: resolves to your server IP

Running Tutorial Tests¶

Once DNS is configured:

# For remote server testing (default)
python scripts/run-all-tutorials.py

# For Docker testing
HOP3_TEST_DOMAIN=hop3-docker.dev python scripts/run-all-tutorials.py

Troubleshooting¶

DNS resolution fails¶

Check if dnsmasq is running:
```
sudo lsof -i :53
```
Restart dnsmasq:
```
sudo pkill dnsmasq
sudo dnsmasq
```
Verify resolver files exist:
```
ls -la /etc/resolver/
```

After reboot¶

dnsmasq must be started manually:

sudo /opt/homebrew/opt/dnsmasq/sbin/dnsmasq

Or configure it to start at boot:

sudo brew services start dnsmasq

Linux Setup¶

On Linux, you can use dnsmasq or NetworkManager:

Using NetworkManager (Ubuntu/Debian)¶

Create /etc/NetworkManager/dnsmasq.d/hop3.conf:
```
address=/hop3.dev/<server-ip>
```

Enable dnsmasq in NetworkManager:

sudo sed -i 's/#dns=dnsmasq/dns=dnsmasq/' /etc/NetworkManager/NetworkManager.conf
sudo systemctl restart NetworkManager

Using systemd-resolved¶

Create /etc/systemd/resolved.conf.d/hop3.conf:

[Resolve]
DNS=127.0.0.1
Domains=~hop3.dev

Add entry to /etc/hosts:
```
<server-ip> *.hop3.dev
```

Note: Linux wildcard DNS support varies by distribution. Testing with explicit hosts entries may be needed.