# radworks-iroh-infra

Ansible playbook to deploy [iroh-relay](https://github.com/n0-computer/iroh/tree/main/iroh-relay) and [iroh-dns-server](https://github.com/n0-computer/iroh/tree/main/iroh-dns-server) to a single host with Caddy as a TLS-terminating reverse proxy.

## Architecture

```
Internet
  |
  +-- TCP 80/443 --> Caddy (auto Let's Encrypt, reverse proxy by hostname)
  |                    |-- relay.example.org --> iroh-relay :3340 (HTTP + WebSocket)
  |                    +-- dns.example.org   --> iroh-dns-server :8080 (HTTP)
  |
  +-- UDP/TCP 53 --> iroh-dns-server (DNS, direct)
  |
  +-- UDP 7842   --> iroh-relay (QUIC address discovery, direct TLS)
```

### TLS termination

Caddy owns ports 80 and 443. It automatically provisions and renews Let's Encrypt certificates for both domains and reverse-proxies HTTPS traffic to each service's plain HTTP listener.

iroh-relay additionally needs its own TLS for QUIC address discovery on UDP port 7842. It uses the `Reloading` cert mode, which reads PEM certificates from disk and automatically picks up changes. A systemd timer (`sync-relay-certs`) copies Caddy's certificates to iroh-relay's cert directory every 12 hours.

The relay config sets `dangerous_http_only = true` in the `[tls]` section. This tells iroh-relay to serve its relay protocol over plain HTTP (so Caddy can proxy it) while still using the TLS configuration for the QUIC endpoint. This works because the QUIC config is built from the TLS settings before the `dangerous_http_only` flag strips TLS from the HTTP listener (see `iroh-relay/src/main.rs:624-696`).

### Port map

| Port | Protocol | Service | Description |
|------|----------|---------|-------------|
| 22 | TCP | sshd | SSH access |
| 53 | TCP+UDP | iroh-dns-server | DNS queries |
| 80 | TCP | Caddy | HTTP (redirects to HTTPS, ACME challenges) |
| 443 | TCP | Caddy | HTTPS reverse proxy to relay and dns-server |
| 3340 | TCP | iroh-relay | Internal HTTP listener (localhost only via Caddy) |
| 7842 | UDP | iroh-relay | QUIC address discovery (direct TLS, not proxied) |
| 8080 | TCP | iroh-dns-server | Internal HTTP listener (localhost only via Caddy) |

## Prerequisites

- A Scaleway (or any Ubuntu/Debian) host with a public IP
- DNS A records pointing to the host (see [DNS records](#dns-records))
- Ansible installed locally (`pip install ansible`)

## DNS records

Create these records at your DNS provider before running the playbook:

| Record | Type | Value |
|--------|------|-------|
| `relay.example.org` | A | server public IP |
| `dns.example.org` | A | server public IP |
| `ns1.dns.example.org` | A | server public IP |

The first two are needed for Caddy to obtain Let's Encrypt certificates. The third is referenced in the DNS SOA and NS records served by iroh-dns-server.

## Usage

### First deploy

1. Edit `inventory/hosts.yml` and set your server IP:
   ```yaml
   iroh01:
     ansible_host: "203.0.113.10"
   ```

2. Run the playbook with your domain configuration:
   ```bash
   ansible-playbook playbook.yml \
     -e domain_relay=relay.example.org \
     -e domain_dns=dns.example.org \
     -e letsencrypt_email=admin@example.org
   ```

### Updating iroh version

Change `iroh_version` in `group_vars/all.yml` (or pass it as an extra var) and re-run the playbook. The new binaries will be downloaded and the services restarted.

```bash
ansible-playbook playbook.yml \
  -e iroh_version=v0.98.0 \
  -e domain_relay=relay.example.org \
  -e domain_dns=dns.example.org \
  -e letsencrypt_email=admin@example.org
```

## Configuration

All variables are defined in `group_vars/all.yml`. Override them with `-e` flags or by editing the file directly.

### Required variables

| Variable | Description | Example |
|----------|-------------|---------|
| `domain_relay` | Hostname for the relay server | `relay.example.org` |
| `domain_dns` | Hostname for the DNS server | `dns.example.org` |
| `letsencrypt_email` | Email for Let's Encrypt registration | `admin@example.org` |

### Optional variables

| Variable | Default | Description |
|----------|---------|-------------|
| `iroh_version` | `v0.97.0` | GitHub release tag to download |
| `iroh_arch` | `x86_64-unknown-linux-musl` | Binary architecture (`aarch64-unknown-linux-musl` for ARM) |
| `iroh_relay_http_port` | `3340` | Internal HTTP port for iroh-relay |
| `iroh_relay_quic_port` | `7842` | QUIC address discovery port |
| `iroh_dns_server_http_port` | `8080` | Internal HTTP port for iroh-dns-server |
| `iroh_dns_server_dns_port` | `53` | DNS listener port |
| `server_ip` | auto-detected | Public IP used in DNS A records (falls back to `ansible_default_ipv4.address`) |

### Service configuration files

The service configs are Jinja2 templates rendered to TOML:

| Template | Rendered to | Docs |
|----------|-------------|------|
| `roles/iroh_relay/templates/iroh-relay.toml.j2` | `/etc/iroh/iroh-relay.toml` | [iroh-relay config](https://github.com/n0-computer/iroh/tree/main/iroh-relay) |
| `roles/iroh_dns_server/templates/iroh-dns-server.toml.j2` | `/etc/iroh/iroh-dns-server.toml` | [iroh-dns-server config](https://github.com/n0-computer/iroh/tree/main/iroh-dns-server) |
| `roles/caddy/templates/Caddyfile.j2` | `/etc/caddy/Caddyfile` | [Caddyfile docs](https://caddyserver.com/docs/caddyfile) |

To add options not exposed as Ansible variables (rate limiting, access control, mainline DHT, etc.), edit the template directly.

## Roles

| Role | What it does |
|------|-------------|
| `common` | Installs packages, creates `iroh` system user, downloads binaries from GitHub releases, disables `systemd-resolved` (frees port 53), configures UFW firewall |
| `caddy` | Installs Caddy from the official apt repo, templates the Caddyfile with reverse proxy rules for both domains |
| `iroh_relay` | Templates relay config and systemd unit, sets up cert-sync timer for QUIC TLS, waits for Caddy certs on first deploy |
| `iroh_dns_server` | Templates DNS server config and systemd unit with `CAP_NET_BIND_SERVICE` for port 53 |

## Systemd services

| Unit | Description |
|------|-------------|
| `caddy.service` | Caddy reverse proxy and TLS terminator |
| `iroh-relay.service` | Iroh relay server |
| `iroh-dns-server.service` | Iroh DNS server |
| `sync-relay-certs.timer` | Copies Caddy's relay certs to iroh-relay every 12 hours |

Check status:
```bash
systemctl status caddy iroh-relay iroh-dns-server sync-relay-certs.timer
```

View logs:
```bash
journalctl -u iroh-relay -f
journalctl -u iroh-dns-server -f
journalctl -u caddy -f
```

## Verifying the deployment

```bash
# Relay responds to HTTPS (WebSocket upgrade expected)
curl -v https://relay.example.org/

# DNS-over-HTTPS
curl https://dns.example.org/dns-query

# Pkarr HTTP API
curl https://dns.example.org/pkarr

# DNS query
dig @dns.example.org example.test
```