simpleguardhome/README.md

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

# 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

• 🔍 Real-time domain filtering status checks
• 🚫 One-click domain unblocking
• 💻 Modern, responsive web interface with Tailwind CSS
• 🔄 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

Requirements

System Requirements

• Python 3.9 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:

docker pull pacnpal/simpleguardhome:latest

2. Create a .env file with your AdGuard Home settings:

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:

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:

version: '3'
services:
  simpleguardhome:
    image: pacnpal/simpleguardhome:latest
    container_name: simpleguardhome
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped

Then run:

docker-compose up -d

Local Installation

1. Clone this repository:

git clone https://github.com/pacnpal/simpleguardhome.git
cd simpleguardhome

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your AdGuard Home settings:

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:

python -m uvicorn src.simpleguardhome.main:app --reload

The application will be available at http://localhost:8000

API Documentation

The API documentation is available at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc
• OpenAPI Schema: http://localhost:8000/api/openapi.json

API Endpoints

All endpoints follow the official AdGuard Home API specification:

Web Interface

• GET / - Main web interface for domain checking and unblocking

Filtering Endpoints

• POST /control/filtering/check_host - Check if a domain is blocked

  • Parameters: name (query parameter)
  • Returns: Detailed filtering status and rules

• POST /control/filtering/whitelist/add - Add a domain to the allowed list

  • Parameters: name (JSON body)
  • Returns: Success status

• 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

Response Models

The application uses Pydantic models that match the AdGuard Home API specification:

FilterStatus

{
    "enabled": bool,
    "filters": [
        {
            "enabled": bool,
            "id": int,
            "name": str,
            "rules_count": int,
            "url": str
        }
    ],
    "user_rules": List[str],
    "whitelist_filters": List[Filter]
}

DomainCheckResult

{
    "reason": str,  # Filtering status (e.g., "FilteredBlackList")
    "rule": str,    # Applied filtering rule
    "filter_id": int,  # ID of the filter containing the rule
    "service_name": str,  # For blocked services
    "cname": str,   # For CNAME rewrites
    "ip_addrs": List[str]  # For A/AAAA rewrites
}

Error Handling

The application implements proper error handling according to the AdGuard Home API spec:

• 400 Bad Request - Invalid input
• 401 Unauthorized - Authentication required
• 403 Forbidden - Authentication failed
• 502 Bad Gateway - AdGuard Home API error
• 503 Service Unavailable - AdGuard Home unreachable

Development

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
├── requirements.txt
├── setup.py
├── .env.example
├── Dockerfile
├── docker-compose.yml
└── README.md

Adding New Features

1. Backend Changes:

   • Add routes in main.py
   • Extend AdGuard client in adguard.py
   • Update configuration in config.py
   • Follow AdGuard Home OpenAPI spec

2. Frontend Changes:

   • Modify templates/index.html
   • Use Tailwind CSS for styling
   • Follow existing error handling patterns

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

License

MIT License - See LICENSE file for details