{"id":31274061,"url":"https://github.com/ryzalain/hagezi-dns-api","last_synced_at":"2026-06-19T08:32:30.227Z","repository":{"id":315672502,"uuid":"1060384375","full_name":"ryzalain/hagezi-dns-api","owner":"ryzalain","description":"Quick and Easy DNS Configuration w/ The Best Blocklists by HaGeZi","archived":false,"fork":false,"pushed_at":"2025-09-19T20:53:01.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T01:45:25.631Z","etag":null,"topics":["dns","docker","hagezi","pi-hole-blocklists","rust","security"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryzalain.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":"2025-09-19T20:25:29.000Z","updated_at":"2025-09-19T21:04:26.000Z","dependencies_parsed_at":"2025-09-20T01:45:27.826Z","dependency_job_id":"6c59519c-507d-439b-8a20-972288429125","html_url":"https://github.com/ryzalain/hagezi-dns-api","commit_stats":null,"previous_names":["ryzalain/hagezi-dns-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ryzalain/hagezi-dns-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryzalain%2Fhagezi-dns-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryzalain%2Fhagezi-dns-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryzalain%2Fhagezi-dns-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryzalain%2Fhagezi-dns-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryzalain","download_url":"https://codeload.github.com/ryzalain/hagezi-dns-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryzalain%2Fhagezi-dns-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34523982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dns","docker","hagezi","pi-hole-blocklists","rust","security"],"created_at":"2025-09-23T22:31:13.470Z","updated_at":"2026-06-19T08:32:30.207Z","avatar_url":"https://github.com/ryzalain.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HaGeZi DNS Blocklist API\n\nA high-performance Rust API backend for serving HaGeZi DNS blocklists with Pi-hole and Docker integration.\n\n## 🚀 Features\n\n- **Fast \u0026 Efficient**: Built with Rust and Axum for maximum performance\n- **Multiple Formats**: Support for domains, hosts, adblock, dnsmasq, wildcard, and RPZ formats\n- **Intelligent Caching**: Built-in caching with TTL and size limits\n- **Pi-hole Integration**: Direct integration with Pi-hole through API endpoints and scripts\n- **Docker Ready**: Complete Docker and Docker Compose setup\n- **RESTful API**: Clean REST API with comprehensive endpoints\n- **Configurable**: Flexible configuration through files and environment variables\n\n## 📋 Table of Contents\n\n- [Quick Start](#quick-start)\n- [API Endpoints](#api-endpoints)\n- [Configuration](#configuration)\n- [Docker Deployment](#docker-deployment)\n- [Pi-hole Integration](#pi-hole-integration)\n- [Development](#development)\n- [Contributing](#contributing)\n\n## 🏃 Quick Start\n\n### Using Docker (Recommended)\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd hagezi-api\n\n# Start with Docker Compose\ndocker-compose up -d\n\n# Check if the API is running\ncurl http://localhost:3000/health\n```\n\n### Manual Installation\n\n```bash\n# Install Rust (if not already installed)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Clone and build\ngit clone \u003crepository-url\u003e\ncd hagezi-api\ncargo build --release\n\n# Run the application\n./target/release/hagezi-api\n```\n\n## 🔌 API Endpoints\n\n### Health \u0026 Status\n\n- `GET /health` - Health check endpoint\n- `GET /api/status` - API status and information\n\n### Blocklist Endpoints\n\n- `GET /api/blocklist/{level}` - Get blocklist by level\n  - Levels: `light`, `normal`, `pro`, `proplus`, `ultimate`\n  - Query parameters:\n    - `format`: `domains`, `hosts`, `adblock`, `dnsmasq`, `wildcard`, `rpz`\n    - `level`: Override the URL level parameter\n\n- `POST /api/compile` - Compile custom blocklist\n  - Body: JSON with compilation parameters\n\n### Pi-hole Integration\n\n- `GET /api/pihole/blocklist/{level}` - Pi-hole optimized blocklist\n- `POST /api/pihole/update` - Trigger Pi-hole update\n- `GET /api/pihole/status` - Pi-hole integration status\n\n### Cache Management\n\n- `GET /api/cache/stats` - Cache statistics\n- `POST /api/cache/clear` - Clear cache\n\n## ⚙️ Configuration\n\n### Configuration File\n\nCreate `config/config.toml`:\n\n```toml\n[server]\nhost = \"0.0.0.0\"\nport = 3000\n\n[cache]\nttl_hours = 24\nmax_size = 100\n\n[fetcher]\ntimeout_seconds = 30\nuser_agent = \"HaGeZi-API/1.0\"\n\n[blocklists]\nbase_url = \"https://raw.githubusercontent.com/hagezi/dns-blocklists/main\"\n\n[pihole]\nenabled = true\nupdate_interval_hours = 6\n```\n\n### Environment Variables\n\nAll configuration options can be overridden with environment variables using the `HAGEZI_` prefix:\n\n```bash\nexport HAGEZI_SERVER_HOST=0.0.0.0\nexport HAGEZI_SERVER_PORT=3000\nexport HAGEZI_CACHE_TTL_HOURS=24\nexport HAGEZI_CACHE_MAX_SIZE=100\nexport HAGEZI_FETCHER_TIMEOUT_SECONDS=30\nexport HAGEZI_FETCHER_USER_AGENT=\"HaGeZi-API/1.0\"\n```\n\n## 🐳 Docker Deployment\n\n### Docker Compose (Recommended)\n\nThe included `docker-compose.yml` provides a complete setup with:\n- HaGeZi API service\n- Pi-hole integration\n- Optional Redis for advanced caching\n\n```bash\n# Start all services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f hagezi-api\n\n# Stop services\ndocker-compose down\n```\n\n### Standalone Docker\n\n```bash\n# Build the image\ndocker build -t hagezi-api .\n\n# Run the container\ndocker run -d \\\n  --name hagezi-api \\\n  -p 3000:3000 \\\n  -e HAGEZI_SERVER_HOST=0.0.0.0 \\\n  -e HAGEZI_SERVER_PORT=3000 \\\n  hagezi-api\n```\n\n## 🥧 Pi-hole Integration\n\n### Automatic Updates\n\nUse the provided script to automatically update Pi-hole with HaGeZi blocklists:\n\n```bash\n# Make the script executable\nchmod +x scripts/pihole-update.sh\n\n# Run with default settings (normal level, domains format)\n./scripts/pihole-update.sh\n\n# Run with custom settings\n./scripts/pihole-update.sh --level pro --format domains --api-url http://localhost:3000\n```\n\n### Cron Job Setup\n\nAdd to your crontab for automatic updates:\n\n```bash\n# Update Pi-hole with HaGeZi blocklists every 6 hours\n0 */6 * * * /path/to/hagezi-api/scripts/pihole-update.sh\n```\n\n### Manual Pi-hole Configuration\n\n1. Access Pi-hole admin interface\n2. Go to Group Management \u003e Adlists\n3. Add the HaGeZi API endpoint:\n   ```\n   http://localhost:3000/api/pihole/blocklist/normal\n   ```\n4. Update gravity: `pihole -g`\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Rust 1.70+ (latest stable recommended)\n- OpenSSL development libraries\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd hagezi-api\n\n# Install dependencies (Ubuntu/Debian)\nsudo apt-get install pkg-config libssl-dev\n\n# Build in development mode\ncargo build\n\n# Run with debug logging\nRUST_LOG=debug cargo run\n\n# Run tests\ncargo test\n\n# Format code\ncargo fmt\n\n# Lint code\ncargo clippy\n```\n\n### Project Structure\n\n```\nhagezi-api/\n├── src/\n│   ├── api/           # API handlers and routes\n│   ├── blocklist/     # Blocklist management\n│   ├── config/        # Configuration handling\n│   ├── error/         # Error types and handling\n│   ├── models/        # Data models\n│   └── main.rs        # Application entry point\n├── config/            # Configuration files\n├── scripts/           # Integration scripts\n├── Dockerfile         # Docker configuration\n├── docker-compose.yml # Docker Compose setup\n└── README.md          # This file\n```\n\n## 📊 API Examples\n\n### Get Normal Level Blocklist in Domains Format\n\n```bash\ncurl \"http://localhost:3000/api/blocklist/normal?format=domains\"\n```\n\n### Get Pro Level Blocklist in Hosts Format\n\n```bash\ncurl \"http://localhost:3000/api/blocklist/pro?format=hosts\"\n```\n\n### Check API Status\n\n```bash\ncurl http://localhost:3000/api/status\n```\n\nResponse:\n```json\n{\n  \"status\": \"healthy\",\n  \"version\": \"1.0.0\",\n  \"uptime\": 3600,\n  \"cache_stats\": {\n    \"entries\": 5,\n    \"hit_rate\": 0.85\n  }\n}\n```\n\n### Pi-hole Optimized Endpoint\n\n```bash\ncurl \"http://localhost:3000/api/pihole/blocklist/normal\"\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n1. **Port already in use**\n   ```bash\n   # Change port in config or environment\n   export HAGEZI_SERVER_PORT=3001\n   ```\n\n2. **SSL/TLS errors**\n   ```bash\n   # Install SSL development libraries\n   sudo apt-get install libssl-dev pkg-config\n   ```\n\n3. **Permission denied (Docker)**\n   ```bash\n   # Add user to docker group\n   sudo usermod -aG docker $USER\n   # Log out and back in\n   ```\n\n### Logging\n\nEnable debug logging:\n```bash\nexport RUST_LOG=hagezi_api=debug,tower_http=debug\n```\n\n### Health Checks\n\nThe API provides several health check endpoints:\n- `/health` - Basic health check\n- `/api/status` - Detailed status information\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n### Code Style\n\n- Use `cargo fmt` for formatting\n- Use `cargo clippy` for linting\n- Write tests for new functionality\n- Update documentation as needed\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [HaGeZi](https://github.com/hagezi/dns-blocklists) for providing excellent DNS blocklists\n- [Pi-hole](https://pi-hole.net/) for the amazing network-wide ad blocking\n- The Rust community for excellent crates and tools\n\n## 📞 Support\n\n- Create an issue for bug reports or feature requests\n- Check existing issues before creating new ones\n- Provide detailed information for faster resolution\n\n---\n\n**Made with ❤️ and Rust**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryzalain%2Fhagezi-dns-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryzalain%2Fhagezi-dns-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryzalain%2Fhagezi-dns-api/lists"}