Add Installation
185
Installation.md
Normal file
185
Installation.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user