From 07c034b9da925f413464c34892fdc31d319d691f Mon Sep 17 00:00:00 2001 From: sq4ind Date: Sun, 28 Sep 2025 12:46:53 +0000 Subject: [PATCH] Add Installation --- Installation.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 Installation.md diff --git a/Installation.md b/Installation.md new file mode 100644 index 0000000..2534edd --- /dev/null +++ b/Installation.md @@ -0,0 +1,185 @@ +# 📦 Installation Guide + +This guide will help you install **AdGuard Control Hub** and get it running in your Home Assistant setup. + +## 📋 Prerequisites + +Before installing, ensure you have: + +- ✅ **Home Assistant 2023.1+** running +- ✅ **AdGuard Home** instance accessible on your network +- ✅ **Admin credentials** for your AdGuard Home +- ✅ **HACS** installed (recommended method) + +## 🔧 Method 1: HACS Installation (Recommended) + +HACS provides the easiest installation and automatic updates. + +### Step 1: Add Custom Repository + +1. Open **Home Assistant** web interface +2. Navigate to **HACS** → **Integrations** +3. Click the menu button **(⋮)** in the top right +4. Select **"Custom repositories"** +5. Add the repository: + - **Repository URL**: `https://your-gitea-domain.com/your-username/adguard-control-hub` + - **Category**: `Integration` +6. Click **"Add"** + +### Step 2: Install Integration + +1. In HACS → Integrations, search for **"AdGuard Control Hub"** +2. Click on the integration when found +3. Click **"Install"** +4. Click **"Install"** again to confirm +5. **Restart Home Assistant** when prompted + +### Step 3: Add Integration to Home Assistant + +1. Go to **Settings** → **Devices & Services** +2. Click **"+ Add Integration"** +3. Search for **"AdGuard Control Hub"** +4. Click on it to start configuration + +## 🛠️ Method 2: Manual Installation + +If you prefer manual installation or don't use HACS: + +### Step 1: Download Files + +1. Go to your repository's releases page +2. Download the latest release ZIP file +3. Extract the archive + +### Step 2: Copy Files + +```bash +# Navigate to your Home Assistant config directory +cd /config + +# Create custom_components directory if it doesn't exist +mkdir -p custom_components + +# Copy the integration files +cp -r /path/to/extracted/custom_components/adguard_hub custom_components/ +``` + +### Step 3: Restart and Configure + +1. **Restart Home Assistant** +2. Go to **Settings** → **Devices & Services** → **"+ Add Integration"** +3. Search for **"AdGuard Control Hub"** + +## ⚙️ Configuration + +When adding the integration, you'll need to provide: + +### Required Settings +- **Host**: IP address or hostname of your AdGuard Home (e.g., `192.168.1.100`) +- **Port**: Port number, usually `3000` for the web interface +- **Username**: Admin username for AdGuard Home +- **Password**: Admin password for AdGuard Home + +### Optional Settings +- **SSL**: Enable if your AdGuard Home uses HTTPS +- **Verify SSL**: Disable for self-signed certificates + +### Example Configuration +``` +Host: 192.168.1.100 +Port: 3000 +Username: admin +Password: your-secure-password +SSL: ☐ (unchecked for HTTP) +Verify SSL: ☑ (checked by default) +``` + +## 🔍 Verification + +After successful configuration, verify the installation: + +### Check Entities Created +1. Go to **Settings** → **Devices & Services** +2. Find **"AdGuard Control Hub"** in the list +3. Click on it to see the device +4. Verify entities are created: + - `switch.adguard_protection` (Global protection) + - `switch.adguard_client_*` (Client switches) + - Various sensors for statistics + +### Test Basic Functionality +1. Go to **Developer Tools** → **States** +2. Find `switch.adguard_protection` +3. Try toggling it on/off +4. Check that the state changes + +## 🚨 Troubleshooting + +### Integration Not Found +- **HACS Users**: Ensure you added the custom repository correctly +- **Manual Users**: Verify files are in the correct location (`custom_components/adguard_hub/`) +- Restart Home Assistant and clear browser cache + +### Cannot Connect Error +```bash +# Test AdGuard Home API access manually +curl -u admin:password http://192.168.1.100:3000/control/status +``` + +**Common solutions**: +- Verify IP address and port +- Check username/password +- Ensure AdGuard Home is running +- Check firewall settings + +### No Entities Created +- Check Home Assistant logs for errors +- Verify AdGuard Home has clients configured +- Try reloading the integration + +### Authentication Issues +- Ensure credentials are correct in AdGuard Home web interface +- Check if account has admin privileges +- Try creating a new admin user specifically for Home Assistant + +## 📊 Post-Installation Setup + +### Enable Debug Logging (Optional) +Add to `configuration.yaml` for troubleshooting: + +```yaml +logger: + default: warning + logs: + custom_components.adguard_hub: debug +``` + +### Configure Update Interval (Optional) +```yaml +# Customize scan interval in configuration.yaml +adguard_hub: + scan_interval: 30 # seconds (default: 30) +``` + +## 🔄 Updates + +### HACS Updates +- HACS will automatically notify you of updates +- Click **"Update"** when available +- Restart Home Assistant after updating + +### Manual Updates +1. Download new release +2. Replace files in `custom_components/adguard_hub/` +3. Restart Home Assistant + +## ✅ Installation Complete! + +Your AdGuard Control Hub should now be installed and ready to use! + +**Next Steps**: +- **[Configuration Guide](Configuration)** - Advanced configuration options +- **[Dashboard Examples](Dashboard-Examples)** - Create control panels +- **[Automation Examples](Automation-Examples)** - Set up automated rules + +Need help? Check the **[Troubleshooting Guide](Troubleshooting)** or open an issue on the repository. \ No newline at end of file