# RootGuard — Self-hosted DNS protection

[Deutsch](#deutsch) · [English](#english)

![RootGuard – Self-hosted DNS protection](assets/rootguard-social-preview.png)

## Product preview

These screenshots show a verified deployment on an isolated test host with the
documented default account. The DNS endpoint address shown belongs to that
disposable test host, not a production or user network; no real network or
access data is included.

![RootGuard dashboard showing protected DNS status, stack metrics, and running services](assets/screenshots/rootguard-dashboard.webp)

![RootGuard guided setup showing the protected DNS chain and completed deployment steps](assets/screenshots/rootguard-guided-setup.webp)

<a id="deutsch"></a>

## Deutsch

**RootGuard schützt alle Geräte in deinem Netzwerk zentral vor Werbung und
bekannten Trackern.** Eine übersichtliche Weboberfläche verbindet dafür
[AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) mit einem eigenen
rekursiven [Unbound](https://github.com/NLnetLabs/unbound)-Resolver – als
vollständiger, selbst betriebener Docker-Compose-Stack für netzwerkweite
DNS-Filterung, rekursive DNS-Auflösung und DNSSEC-Validierung.

[![Release](https://img.shields.io/github/v/release/foxly-it/rootguard?include_prereleases&label=release)](https://github.com/foxly-it/rootguard/releases)
[![CI](https://github.com/foxly-it/rootguard/actions/workflows/ci.yml/badge.svg)](https://github.com/foxly-it/rootguard/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/foxly-it/rootguard)](LICENSE)
[![Website](https://img.shields.io/badge/website-rootguard.foxly.de-72c483)](https://rootguard.foxly.de/)

[Website](https://rootguard.foxly.de/) ·
[Handbuch](https://rootguard.foxly.de/docs/) ·
[Roadmap](https://rootguard.foxly.de/roadmap.html) ·
[Releases](https://github.com/foxly-it/rootguard/releases)

> [!NOTE]
> RootGuard 1.0 ist erschienen. Kernpfade, Updates mit Rollback und
> unveränderliche, attestierte Releases sind produktionsreif - wie bei jeder
> Netzwerkinfrastruktur empfiehlt sich trotzdem, Backups und einen
> alternativen DNS-Weg bereitzuhalten.

## Warum RootGuard?

Ein DNS-Filter kann Werbung und Tracker für Fernseher, Smartphones,
Spielekonsolen und Computer blockieren, ohne auf jedem Gerät eine Erweiterung
zu installieren. RootGuard ergänzt diese Filterung um einen eigenen Resolver
und eine gemeinsame Bedienoberfläche.

- **Netzwerkweite Filterung:** AdGuard Home stoppt unerwünschte DNS-Anfragen.
- **Eigene DNS-Auflösung:** Unbound fragt die DNS-Hierarchie rekursiv ab und
  validiert DNSSEC.
- **Zentrale Verwaltung:** Geführtes Setup, Konfiguration, Updates,
  Health-Checks, Diagnose und Rollbacks laufen über die RootGuard-Weboberfläche.
- **Geführtes lokales DNS:** Lokale Einträge, private Domains, Conditional
  Forwarding und sichere RFC1918-Reverse-Zonen kommen ohne rohe
  Unbound-Konfiguration aus.
- **Self-hosted und offen:** Daten und Kontrolle bleiben auf dem eigenen
  Docker-Host; der Quellcode ist unter AGPL-3.0-or-later verfügbar.

```text
Geräte im Netzwerk → AdGuard Home → Unbound → DNS-Hierarchie
                         Filter       DNSSEC
```

## Quick Start

Voraussetzung ist ein Rechner mit Docker Compose v2. RootGuard verwendet
fertige Images für `amd64` und `arm64`; ein lokaler Build ist nicht
notwendig.

```sh
mkdir rootguard && cd rootguard
curl -LO https://raw.githubusercontent.com/foxly-it/rootguard/v1.0.12/compose.release.yaml
curl -Lo .env https://raw.githubusercontent.com/foxly-it/rootguard/v1.0.12/.env.release.example
```

Erzeuge zwei voneinander unabhängige Sicherheitsschlüssel:

```sh
openssl rand -hex 32
openssl rand -hex 32
```

Trage in `.env` ein eigenes starkes `ROOTGUARD_ADMIN_PASSWORD` sowie die beiden
Werte getrennt als `ROOTGUARD_API_TOKEN` und `ROOTGUARD_RECOVERY_TOKEN` ein.
Starte anschließend den Stack:

```sh
docker compose -f compose.release.yaml up -d
```

Öffne `http://<IP-des-Docker-Hosts>:8080/login` und folge dem geführten Setup.
Dabei kannst du zwischen dem empfohlenen Stable-Kanal und einer ausdrücklich
als experimentell gekennzeichneten AdGuard-Home-Beta wählen. Beta kann Fehler
enthalten; DNS-Auflösung und Blocking dürfen deshalb nicht als ausfallsicher
betrachtet werden.
Die vollständigen Voraussetzungen, Router-Einrichtung und Fehlerbehebung stehen
im [Handbuch](https://rootguard.foxly.de/docs/getting-started/).

## Was ist enthalten?

| Komponente | Aufgabe |
| --- | --- |
| **RootGuard WebApp** | Login, Dashboard und geführte Bedienung |
| **RootGuard Core** | Orchestrierung und geprüfte Konfigurationsänderungen |
| **RootGuard Updater** | Gemeinsame Core-/WebApp-Updates mit Rollback |
| **AdGuard Home** | Netzwerkweite DNS-Filterung |
| **Unbound** | Rekursive DNS-Auflösung und DNSSEC-Validierung |

Die [Live-Produktansicht](https://rootguard.foxly.de/) zeigt die aktuelle
Oberfläche. Architektur, Vertrauensgrenzen und Update-Abläufe sind bewusst aus
diesem Einstieg ausgelagert:

- [Installation und Betrieb](https://rootguard.foxly.de/docs/)
- [Architektur](docs/architecture.md)
- [Aktueller Projektstand](docs/project-state.md)
- [Roadmap bis 1.0](ROADMAP.md)
- [Changelog](CHANGELOG.md)
- [Image-Digests und Aufbewahrungsregeln](docs/image-retention-policy.md)
- [Geprüfte Installationsplattformen](docs/platform-support.md)
- [Performance- und Speicher-Baseline](docs/performance-baseline.md)
- [Barrierefreiheits- und Sicherheits-Review](docs/accessibility-security-review.md)

## Entwicklung

RootGuard ist ein Monorepo. Für Änderungen am gesamten Projekt reicht ein
einfacher Klon:

```sh
git clone https://github.com/foxly-it/rootguard.git
cd rootguard
cp .env.example .env
docker compose up --build -d
```

Die Komponenten sind eigenständig baubare Verzeichnisse im selben Repository:

| Verzeichnis | Verantwortung |
| --- | --- |
| [`rootguard-core`](rootguard-core) | Control Plane und DNS-Orchestrierung |
| [`rootguard-webapp`](rootguard-webapp) | Weboberfläche und Sitzungsverwaltung |
| [`rootguard-updater`](rootguard-updater) | Kontrollierte Control-Plane-Updates |
| [`rootguard-unbound`](rootguard-unbound) | Gehärtetes Unbound-Image |
| [`rootguard-blockpage`](rootguard-blockpage) | Landingpage für geblockte Anfragen |
| [`rootguard-attestation-proxy`](rootguard-attestation-proxy) | Egress-Proxy für Cosign-Attestierungsprüfungen |

Die vormaligen eigenständigen Repositories sind archiviert und weiterhin
lesbar (Historie, alte Issues/PRs); aktive Entwicklung findet nur noch hier
statt.

## Qualitätssicherung

Neben menschlichem Code-Review setzt dieses Projekt Claude (Anthropic) als
KI-gestütztes Werkzeug ein, um Fehler und Sicherheitsrisiken im Code zu
finden, bevor sie ausgeliefert werden – vergleichbar mit einem zusätzlichen,
automatisierten Reviewer. Jeder Befund wird von einem Menschen geprüft und
erst nach eigener Verifikation behoben; nichts wird ungeprüft übernommen.
Der vollständige, chronologische Verlauf aller bisherigen Audit-Runden
inklusive Befunden und Fixes steht öffentlich in
[docs/security-audit-log.md](docs/security-audit-log.md).

## Mitwirken

Beiträge, Tests und verständliche Dokumentation sind willkommen. Der
[Beitragsleitfaden](CONTRIBUTING.md) erklärt Entwicklungssetup, Zuständigkeiten,
Tests und Pull Requests.

Ein guter Einstieg sind Issues mit
[`good first issue`](https://github.com/foxly-it/rootguard/labels/good%20first%20issue)
oder [`help wanted`](https://github.com/foxly-it/rootguard/labels/help%20wanted).
Sicherheitsprobleme bitte nicht öffentlich melden, sondern den Hinweisen in
[SECURITY.md](SECURITY.md) folgen.

## Lizenz und Marke

RootGuard ist freie Software unter
[GNU AGPL-3.0-or-later](LICENSE). Hinweise zur Nutzung der Namen und Logos von
RootGuard und Foxly IT stehen in [TRADEMARKS.md](TRADEMARKS.md).

---

<a id="english"></a>

## English

**RootGuard centrally protects every device on your network from ads and known
trackers.** Its approachable web interface combines
[AdGuard Home](https://github.com/AdguardTeam/AdGuardHome) with a private,
recursive [Unbound](https://github.com/NLnetLabs/unbound) resolver in one
self-hosted Docker Compose stack for network-wide DNS filtering, recursive DNS,
and DNSSEC validation.

[Website](https://rootguard.foxly.de/) ·
[Documentation](https://rootguard.foxly.de/docs/) ·
[Roadmap](https://rootguard.foxly.de/roadmap.html) ·
[Releases](https://github.com/foxly-it/rootguard/releases)

> [!NOTE]
> RootGuard 1.0 has shipped. Core paths, updates with rollback, and
> immutable, attested releases are production-ready - as with any network
> infrastructure, keep backups and an alternative DNS path available
> regardless.

### Why RootGuard?

A DNS filter can block ads and trackers for TVs, smartphones, game consoles,
computers, and IoT devices without installing an extension on every device.
RootGuard adds a private recursive resolver and one coherent management
interface.

- **Network-wide ad and tracker blocking:** AdGuard Home filters unwanted DNS
  requests before they reach your devices.
- **Private recursive DNS:** Unbound resolves names through the DNS hierarchy
  and validates DNSSEC signatures.
- **Unified management:** Guided setup, configuration, updates, health checks,
  diagnostics, and rollbacks live in the RootGuard WebGUI.
- **Guided local DNS:** Manage local records, private domains, conditional
  forwarding, and RFC1918 reverse zones without editing raw Unbound files.
- **Self-hosted and open source:** Data and control remain on your Docker host;
  the source is available under AGPL-3.0-or-later.

```text
Network devices → AdGuard Home → Unbound → DNS hierarchy
                       filtering      DNSSEC
```

### Quick start

RootGuard requires Docker Compose v2. It provides ready-made `amd64` and
`arm64` container images, so no local build is required.

```sh
mkdir rootguard && cd rootguard
curl -LO https://raw.githubusercontent.com/foxly-it/rootguard/v1.0.12/compose.release.yaml
curl -Lo .env https://raw.githubusercontent.com/foxly-it/rootguard/v1.0.12/.env.release.example
```

Generate two independent random security tokens:

```sh
openssl rand -hex 32
openssl rand -hex 32
```

Set a strong `ROOTGUARD_ADMIN_PASSWORD` in `.env` and use the generated values
separately for `ROOTGUARD_API_TOKEN` and `ROOTGUARD_RECOVERY_TOKEN`. Then start
the stack:

```sh
docker compose -f compose.release.yaml up -d
```

Open `http://<docker-host-ip>:8080/login` and follow the guided setup. The setup
offers the recommended Stable channel and an explicitly experimental
AdGuard Home Beta channel. Beta may contain bugs; DNS resolution and blocking
must not be treated as fail-safe when it is selected. See the
[installation guide](https://rootguard.foxly.de/docs/getting-started/) for
requirements, router configuration, upgrades, and troubleshooting.

### Included components

| Component | Responsibility |
| --- | --- |
| **RootGuard WebApp** | Login, dashboard, and guided management |
| **RootGuard Core** | Orchestration and validated configuration changes |
| **RootGuard Updater** | Coordinated Core/WebApp updates with rollback |
| **AdGuard Home** | Network-wide DNS filtering |
| **Unbound** | Recursive DNS resolution and DNSSEC validation |

Further technical information:

- [Architecture and trust boundaries](docs/architecture.md)
- [Current project state](docs/project-state.md)
- [Roadmap to 1.0](ROADMAP.md)
- [Changelog](CHANGELOG.md)
- [Image digests and retention policy](docs/image-retention-policy.md)
- [Verified installation platforms](docs/platform-support.md)
- [Performance and memory baseline](docs/performance-baseline.md)
- [Accessibility and security review](docs/accessibility-security-review.md)

### Development

RootGuard is a monorepo, so a plain clone is enough:

```sh
git clone https://github.com/foxly-it/rootguard.git
cd rootguard
cp .env.example .env
docker compose up --build -d
```

The components are independently buildable directories in the same
repository:

| Directory | Responsibility |
| --- | --- |
| [`rootguard-core`](rootguard-core) | Control plane and DNS orchestration |
| [`rootguard-webapp`](rootguard-webapp) | Web interface and session management |
| [`rootguard-updater`](rootguard-updater) | Coordinated control-plane updates |
| [`rootguard-unbound`](rootguard-unbound) | Hardened Unbound image |
| [`rootguard-blockpage`](rootguard-blockpage) | Landing page for blocked requests |
| [`rootguard-attestation-proxy`](rootguard-attestation-proxy) | Egress proxy for cosign attestation checks |

The formerly separate repositories are archived and still readable (history,
old issues/PRs); active development happens only here now.

### Quality assurance

Alongside human code review, this project uses Claude (Anthropic) as an
AI-assisted tool to find bugs and security risks in the code before they
ship - comparable to an additional, automated reviewer. Every finding is
verified by a human before being fixed; nothing is accepted unreviewed. The
full, chronological record of every audit round, including findings and
fixes, is public in
[docs/security-audit-log.md](docs/security-audit-log.md).

### Contributing

Contributions, testing, and clear documentation are welcome. Read
[CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Good
starting points are issues labeled
[`good first issue`](https://github.com/foxly-it/rootguard/labels/good%20first%20issue)
or [`help wanted`](https://github.com/foxly-it/rootguard/labels/help%20wanted).
Report security vulnerabilities privately by following
[SECURITY.md](SECURITY.md), not in a public issue.

### License and trademark

RootGuard is free and open-source software licensed under
[GNU AGPL-3.0-or-later](LICENSE). See [TRADEMARKS.md](TRADEMARKS.md) for the
RootGuard and Foxly IT name and logo policy.