{"id":46182959,"url":"https://github.com/emotionalamo/rust-dns-backend","last_synced_at":"2026-04-01T21:54:11.197Z","repository":{"id":341247923,"uuid":"1169407516","full_name":"EmotionalAmo/rust-dns-backend","owner":"EmotionalAmo","description":"DNS ad-blocker for your homelab. Written in Rust. 4.6 MB RAM.","archived":false,"fork":false,"pushed_at":"2026-03-06T07:17:47.000Z","size":60165,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T11:45:51.307Z","etag":null,"topics":["ad-blocker","dns","dns-over-https","homelab","raspberry-pi","rust","self-hosted"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EmotionalAmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T16:37:55.000Z","updated_at":"2026-03-06T07:17:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"3123d21f-5096-44f5-b1d8-0ba5c0e50bf0","html_url":"https://github.com/EmotionalAmo/rust-dns-backend","commit_stats":null,"previous_names":["emotionalamo/rust-dns-backend"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/EmotionalAmo/rust-dns-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmotionalAmo%2Frust-dns-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmotionalAmo%2Frust-dns-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmotionalAmo%2Frust-dns-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmotionalAmo%2Frust-dns-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EmotionalAmo","download_url":"https://codeload.github.com/EmotionalAmo/rust-dns-backend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmotionalAmo%2Frust-dns-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30253938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T08:59:44.879Z","status":"ssl_error","status_checked_at":"2026-03-08T08:58:02.867Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ad-blocker","dns","dns-over-https","homelab","raspberry-pi","rust","self-hosted"],"created_at":"2026-03-02T21:00:25.509Z","updated_at":"2026-04-01T21:54:11.179Z","avatar_url":"https://github.com/EmotionalAmo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rust-dns\n\n**DNS ad-blocker for your homelab. Written in Rust. 4.6 MB RAM. No GC pauses.**\n\nIf Pi-hole v6 broke your setup — the 403 errors, the UI crashes, the config migration that ate your groups — you are not alone. rust-dns is a single binary that just works.\n\n[![GitHub Stars](https://img.shields.io/github/stars/EmotionalAmo/rust-dns-backend?style=flat-square)](https://github.com/EmotionalAmo/rust-dns-backend)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)\n[![v1.9.1](https://img.shields.io/badge/version-v1.9.1-orange?style=flat-square)](https://github.com/EmotionalAmo/rust-dns-backend/releases)\n\n---\n\n## Why rust-dns?\n\n| | rust-dns | Pi-hole v6 | AdGuard Home |\n|---|---|---|---|\n| Language | Rust | C + Python | Go |\n| Memory usage | **4.6 MB** | ~50–100 MB | ~39 MB |\n| Deployment | Single binary | Multi-component | Single binary |\n| GC pauses | None | Yes | Yes |\n| Telemetry | None | None | Optional |\n\nBenchmarked on Docker (idle, with blocklists loaded). AdGuard Home measured at 39.2 MB under same conditions — rust-dns uses **8.5x less memory**.\n\nWorks great on a Raspberry Pi 4, a $4 VPS, or anything else you have sitting in the rack.\n\n### Coming from Pi-hole v6?\n\nPi-hole v6 shipped with a rewritten core and broke a lot of setups: groups not migrating, the web UI returning 403s, systemd unit changes. If you spent a weekend debugging and just want something that works, rust-dns is a 5-minute Docker deploy with zero migration headaches. Your old blocklist URLs still work — paste them in and you're done.\n\n---\n\n## Quick Start (Docker)\n\n**One command to start filtering DNS:**\n\n```bash\ndocker run -d \\\n  --name rust-dns \\\n  --restart unless-stopped \\\n  -p 53:53/udp \\\n  -p 53:53/tcp \\\n  -p 8080:8080 \\\n  -v rust-dns-data:/data/rust-dns \\\n  -e RUST_DNS__AUTH__JWT_SECRET=$(openssl rand -hex 32) \\\n  ghcr.io/emotionalamo/rust-dns-backend:latest\n```\n\nOpen `http://localhost:8080` — default login: `admin / admin` (change this immediately).\n\nOr with Docker Compose:\n\n```bash\ngit clone https://github.com/EmotionalAmo/rust-dns-backend.git\ncd rust-dns-backend\necho \"RUST_DNS__AUTH__JWT_SECRET=$(openssl rand -hex 32)\" \u003e .env\ndocker compose up -d\n```\n\nPoint your router (or Pi's `/etc/resolv.conf`) to this machine's IP on port 53. Done.\n\n---\n\n## What It Does\n\n- **DNS filtering** — block ads, trackers, and malware domains via blocklists\n- **DNS over HTTPS (DoH)** — encrypted upstream queries\n- **Bulk rule import** — upload a file or paste text directly; supports dual-tab for rules and allowlist\n- **Top queried domains** — see what's actually hitting your DNS, not just block counts\n- **REST API** — full management API, consumed by the web dashboard\n- **Caching** — in-memory cache, zero cold-start latency on warm queries\n- **Web UI** — clean dashboard with English and Chinese (i18n) support\n- **SQLite storage** — one file, easy to back up, no database server needed\n\n---\n\n## Configuration\n\nAll configuration is done via environment variables.\n\n| Variable | Default | Description |\n|---|---|---|\n| `RUST_DNS__AUTH__JWT_SECRET` | **(required)** | Secret for signing JWT tokens. Use a random 32+ byte string. |\n| `RUST_DNS__DATABASE__PATH` | `/data/rust-dns/rust-dns.db` | Path to the SQLite database file. |\n| `RUST_DNS__DNS__PORT` | `53` | DNS server port (UDP + TCP). |\n| `RUST_DNS__API__PORT` | `8080` | Management API and dashboard port. |\n| `RUST_DNS__API__STATIC_DIR` | `/opt/rust-dns/static` | Path to frontend static assets. |\n| `RUST_LOG` | `rust_dns=info` | Log level. Use `debug` for troubleshooting. |\n\n**Security note:** Change the default `admin/admin` credentials immediately after first login. Never use the placeholder `CHANGE_ME` JWT secret in production.\n\n---\n\n## Ports\n\n| Port | Protocol | Purpose |\n|---|---|---|\n| `53` | UDP + TCP | DNS queries |\n| `8080` | TCP | REST API + Web UI |\n\n---\n\n## Build from Source\n\n```bash\n# Requires Rust 1.93+\ngit clone https://github.com/EmotionalAmo/rust-dns-backend.git\ncd rust-dns-backend\n\ncargo build --release\n\n# Binding port 53 requires elevated privileges on Linux\nsudo ./target/release/rust-dns\n```\n\n---\n\n## Security\n\n- All API endpoints require JWT authentication\n- Non-root container: runs as a dedicated `rust-dns` user\n- CI enforces `cargo clippy`, `cargo fmt`, and `cargo audit` on every push\n- No telemetry, no phone-home, no cloud dependency\n\n---\n\n## Project Status\n\nv1.9.1 — actively developed. Core DNS filtering and API are stable. Recent releases added bulk rule import, query analytics, and i18n support.\n\nRoadmap items and known issues are tracked in [GitHub Issues](https://github.com/EmotionalAmo/rust-dns-backend/issues).\n\n---\n\n## Contributing\n\nThe codebase is small enough to read in an afternoon. If you want to add a feature or fix something, [browse the good first issues](https://github.com/EmotionalAmo/rust-dns-backend/issues?q=is%3Aopen+label%3A%22good+first+issue%22) — they're real missing features, not busywork. PRs welcome; no CLA required.\n\n```bash\n# Fork, clone, then:\ncargo test\ncargo clippy -- -D warnings\ncargo fmt --check\n```\n\n---\n\n## License\n\nApache 2.0 — use it, fork it, ship it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femotionalamo%2Frust-dns-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femotionalamo%2Frust-dns-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femotionalamo%2Frust-dns-backend/lists"}