simpleguardhome/README.md

<p align="center">
  <img src="static/simpleguardhome.png" alt="SimpleGuardHome Logo" width="200">
</p>

<h1 align="center">SimpleGuardHome</h1>

<p align="center">
  <a href="https://github.com/pacnpal/simpleguardhome/releases"><img src="https://img.shields.io/badge/version-0.1.0-blue.svg" alt="Version 0.1.0"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  <a href="#requirements"><img src="https://img.shields.io/badge/python-3.7+-blue.svg" alt="Python 3.7+"></a>
</p>

A modern web application for checking and adding domains to custom filtering rules in AdGuard Home. Built with FastAPI and modern JavaScript, following the official AdGuard Home OpenAPI specification. Meant as a simple AdGuard Home web interface for users to check if a domain is blocked, and then add it.

## 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

## 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`

## 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
├── 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