SimpleGuardHome
A modern web application for checking and managing domain filtering in AdGuard Home. Built with FastAPI and modern JavaScript, following the official AdGuard Home OpenAPI specification.
## Quick Start
```bash
# Using Docker
docker run -d -p 8000:8000 -e ADGUARD_HOST=http://localhost -e ADGUARD_PORT=3000 pacnpal/simpleguardhome:latest
# Or using Python
pip install simpleguardhome
python -m uvicorn simpleguardhome.main:app --port 8000
```
Then visit `http://localhost:8000` to start managing your AdGuard Home filtering.
## Features
### Core Features
- 🔍 Real-time domain filtering status checks
- 🚫 One-click domain unblocking
- 💻 Modern, responsive web interface with Tailwind CSS
- 🌓 Support for light and dark modes
- 🔄 Live feedback and error handling
- 📝 Comprehensive logging
- 🏥 Health monitoring endpoint
- ⚙️ Environment-based configuration
- 📚 Full OpenAPI/Swagger documentation
- ✅ Implements official AdGuard Home API spec
- 🐳 Docker support
### Browser Integration
- 🔎 404 Page Checker Userscript
- Automatically detects 404 responses while browsing
- Checks if failed domains are blocked by AdGuard Home
- Shows unblock notifications with one-click actions
- Configurable settings and caching system
- Tampermonkey integration for all major browsers
## Requirements
### System Requirements
- Python 3.7 or higher (for local installation)
- Running AdGuard Home instance
- AdGuard Home API credentials
- Docker (optional, for containerized deployment)
### Python Dependencies
- FastAPI - Web framework for building APIs
- Uvicorn - ASGI server implementation
- Python-dotenv - Environment variable management
- HTTPX - Modern HTTP client
- Pydantic - Data validation using Python type annotations
- Jinja2 - Template engine for the web interface
## Docker Installation
The easiest way to get started is using Docker:
1. Pull the Docker image:
```bash
docker pull pacnpal/simpleguardhome:latest
```
2. Create a `.env` file with your AdGuard Home settings:
```env
ADGUARD_HOST=http://localhost # AdGuard Home host URL
ADGUARD_PORT=3000 # AdGuard Home API port
ADGUARD_USERNAME=admin # Required: AdGuard Home username
ADGUARD_PASSWORD=password # Required: AdGuard Home password
```
3. Run the container:
```bash
docker run -d \
--name simpleguardhome \
-p 8000:8000 \
--env-file .env \
pacnpal/simpleguardhome:latest
```
The application will be available at `http://localhost:8000`
### Docker Compose
Alternatively, you can use Docker Compose. Create a `docker-compose.yml` file:
```yaml
version: '3'
services:
simpleguardhome:
image: pacnpal/simpleguardhome:latest
container_name: simpleguardhome
ports:
- "8000:8000"
env_file:
- .env
restart: unless-stopped
```
Then run:
```bash
docker-compose up -d
```
## Local Installation
1. Clone this repository:
```bash
git clone https://github.com/pacnpal/simpleguardhome.git
cd simpleguardhome
```
2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
## Configuration
1. Copy the example environment file:
```bash
cp .env.example .env
```
2. Edit `.env` with your AdGuard Home settings:
```env
ADGUARD_HOST=http://localhost # AdGuard Home host URL
ADGUARD_PORT=3000 # AdGuard Home API port
ADGUARD_USERNAME=admin # Required: AdGuard Home username
ADGUARD_PASSWORD=password # Required: AdGuard Home password
```
## Running the Application
### Local Development
Start the application:
```bash
python -m uvicorn src.simpleguardhome.main:app --reload
```
The application will be available at `http://localhost:8000`
## Browser Integration Setup
1. Install the [Tampermonkey](https://www.tampermonkey.net/) browser extension
2. Navigate to the `userscript` directory in this repository
3. Install the `simpleguardhome-404-checker.user.js` script
4. Configure the script with your AdGuard Home instance details
The userscript will automatically:
- Monitor web requests for 404 responses
- Check if failed domains are blocked
- Show notifications for blocked domains
- Provide quick unblock options
## API Documentation
The API documentation is automatically generated by FastAPI using:
- Type hints in endpoint definitions
- Pydantic models for request/response validation
- Function docstrings for descriptions
- Response models and status codes
Documentation is available at:
- Swagger UI: `http://localhost:8000/api/docs` - Interactive API documentation
- ReDoc: `http://localhost:8000/api/redoc` - Alternative documentation UI
- OpenAPI Schema: `http://localhost:8000/api/openapi.json` - Raw OpenAPI specification
### API Endpoints
All endpoints follow the official AdGuard Home API specification:
#### Web Interface
- `GET /` - Main web interface for domain checking and unblocking
#### Filtering Endpoints
- `GET /control/filtering/check_host` - Check if a domain is blocked
- Parameters: `name` (query parameter)
- Returns: Detailed filtering status and rules
- `GET /control/filtering/unblock_host` - Unblock a domain by adding it to whitelist
- Parameters: `name` (query parameter)
- Returns: Success message with domain status
- Status: Returns whether domain was unblocked, already unblocked, or not blocked
- `POST /control/filtering/set_rules` - Add domains to the filtering rules
- Parameters: Array of rules in request body
- Returns: Success message on successful update
- Note: Used internally by unblock_host endpoint
- `GET /control/filtering/status` - Get current filtering configuration
- Returns: Complete filtering status including rules and filters
#### System Status
- `GET /control/status` - Check application and AdGuard Home connection status
- Returns: Health status with filtering state
## Project Structure
```
simpleguardhome/
├── src/
│ └── simpleguardhome/
│ ├── __init__.py
│ ├── main.py # FastAPI application
│ ├── config.py # Configuration management
│ ├── adguard.py # AdGuard Home API client
│ └── templates/
│ └── index.html # Web interface
├── static/
│ └── simpleguardhome.png # Project logo
├── userscript/
│ ├── README.md # Userscript documentation
│ └── simpleguardhome-404-checker.user.js
├── rules_backup/ # Backup storage location
├── requirements.txt
├── setup.py
├── pyproject.toml # Project metadata and dependencies
├── .env.example
├── Dockerfile
└── README.md
```
## Security Notes
- API credentials are handled via environment variables
- Connections use proper error handling and timeouts
- Input validation is performed on all endpoints
- CORS protection with proper headers
- Rate limiting on sensitive endpoints
- Session-based authentication with AdGuard Home
- Sensitive information is not exposed in responses
## Error Handling
The application implements comprehensive error handling according to endpoint:
GET /control/filtering/check_host:
- 400: Invalid domain format or missing name parameter
- 503: AdGuard Home service unavailable
GET /control/filtering/unblock_host:
- 400: Invalid domain format or missing name parameter
- 500: Failed to unblock domain
- 503: AdGuard Home service unavailable
POST /control/filtering/set_rules:
- 400: Invalid rule format or missing rules
- 500: Failed to update rules
- 503: AdGuard Home service unavailable
All endpoints return an ErrorResponse model with a descriptive message.
## Response Models
The application uses Pydantic models that match the AdGuard Home API specification:
### FilterStatus
```python
{
"enabled": bool,
"filters": [
{
"enabled": bool,
"id": int,
"name": str,
"rules_count": int,
"url": str
}
],
"user_rules": List[str],
"whitelist_filters": List[Filter]
}
```
### FilterCheckHostResponse
```python
{
"reason": str, # Filtering status (e.g., "FilteredBlackList", "NotFilteredNotFound")
"filter_id": int, # Optional: ID of the filter containing the rule (deprecated)
"rule": str, # Optional: Applied filtering rule (deprecated)
"rules": [ # List of applied rules with details
{
"filter_list_id": int, # Filter list ID
"text": str # Rule text
}
],
"service_name": str, # Optional: For blocked services
"cname": str, # Optional: For CNAME rewrites
"ip_addrs": List[str] # Optional: For A/AAAA rewrites
}
```
### SetRulesRequest
```python
{
"rules": List[str] # List of filtering rules to set
}
```
### ErrorResponse
```python
{
"message": str # Error description
}
```
## License
MIT License - See LICENSE file for details