# AdGuard DNS Rewrite Opportunities ## Overview AdGuard DNS at `192.168.1.2` can handle internal domain resolution, eliminating need for external DNS or hosts file entries. ## Current Setup - **AdGuard URL**: `http://192.168.1.2` - **Status**: Running on Proxmox **LXC 102** (`dns`, 192.168.1.2) - **Homepage widget**: Configured ## AI Service DNS Entries ### Recommended DNS Rewrites Add these static DNS entries in AdGuard to resolve AI services locally: | Domain | IP Address | TTL | Purpose | |--------|------------|-----|---------| | `ai.nuclide.systems` | `192.168.1.40` | 300 | LiteLLM gateway | | `chat.nuclide.systems` | `192.168.1.40` | 300 | LobeHub chat | | `mcp.nuclide.systems` | `192.168.1.40` | 300 | MCP servers | | `litellm.nuclide.systems` | `192.168.1.40` | 300 | LiteLLM API | | `s3.nuclide.systems` | `192.168.1.40` | 300 | Garage S3 (Zoraxy proxy) | ### Benefits 1. **No external DNS needed** - All AI services resolve internally 2. **Failover protection** - Works even if external DNS is unreachable 3. **Faster resolution** - Local DNS vs external lookup 4. **Simplified client config** - Services can use domain names directly ## How to Add ### Method 1: Web UI (Recommended) 1. Open AdGuard: `http://192.168.1.2` (or via Zone: `http://192.168.1.2:3000`) 2. Navigate to **DNS Settings** → **Static DNS Entries** 3. Click **Add** for each service: ``` Domain: ai.nuclide.systems IP Address: 192.168.1.40 TTL: 300 ``` 4. Click **Save** ### Method 2: API ```bash # Get session token first curl -c /tmp/cookies.txt -k -X POST http://192.168.1.2:3000/ \ -H "Content-Type: application/json" \ -d "{\"username\": \"root\", \"password\": \"${ADGUARD_PASSWORD}\"}" # Export ADGUARD_PASSWORD from your shell env or a `.env` file — never hardcode. # Add static DNS entry curl -s -k -c /tmp/cookies.txt -b /tmp/cookies.txt \ -X POST http://192.168.1.2:3000/admin/api/staticDNS \ -H "Content-Type: application/json" \ -d '{ "domain": "ai.nuclide.systems", "ip": "192.168.1.40", "ttl": 300 }' ``` ### Method 3: Auto-configure (Script) Create `/opt/stacks/scripts/configure_adguard_dns.sh`: ```bash #!/bin/bash # Configure AdGuard DNS for AI stack ADGUARD_HOST="192.168.1.2" ADGUARD_PORT="3000" TARGET_IP="192.168.1.40" # AI service domains to add DOMAINS=( "ai.nuclide.systems" "chat.nuclide.systems" "mcp.nuclide.systems" "litellm.nuclide.systems" "s3.nuclide.systems" ) echo "🔧 Adding DNS entries to AdGuard..." for domain in "${DOMAINS[@]}"; do echo " → $domain → $TARGET_IP" # Note: This is a placeholder - actual API call needed done echo "✅ Done! Add these in AdGuard UI manually." ``` ## `*.nuclide.lan` zone (LAN-only aliases, added 2026-05-24) 30 A-records mapping stable names to host IPs. Use cases: (a) bypass Zoraxy for direct LAN access (Immich app on home Wi-Fi `nuclide`, NAS browsers, infra admin UIs), (b) decouple client config from IPs so when a service moves CT only the AdGuard rewrite changes. Naming convention: - **Per-host** (one per CT/VM/device): `unifi`, `dlink`, `pve`, `adguard`, `backrest`, `zoraxy`, `id`, `db`, `secrets`, `ops`, `nas`, `docker`, `nextcloud`, `dev`, `shepard`, `ha`, `mainsail` - **Per-service** (alias when only port differs from the host): `immich`, `vault`, `karakeep`, `memos`, `abs`, `gotify`, `n8n`, `chat`, `ai`, `mcp`, `grafana`, `prometheus`, `homarr` Full list in `/opt/AdGuardHome/AdGuardHome.yaml` under `dns.rewrites:`. Auto-pushed nightly to [`fkrebs/adguard-conf`](https://git.nuclide.systems/fkrebs/adguard-conf). **Adding a new service alias:** 1. Append a `- {domain: .nuclide.lan, answer: 192.168.x.y, enabled: true}` line 2. `systemctl restart AdGuardHome` on CT 102 (AdGuard doesn't support `reload` for rewrites) 3. Verify: `dig +short @192.168.1.2 .nuclide.lan` **When a service moves CT (changes IP):** edit only the AdGuard rewrite → restart. No client app needs an update — this is the whole point of the alias zone. ## Alternative Useful DNS Entries ### NextCloud & Sync - `nc.nuclide.systems` → `192.168.1.40` (NextCloud web) - `sync.nuclide.systems` → Internal IP of Sync client ### Garage S3 - `storage.nuclide.systems` → `192.168.1.40` (Garage internal, port 3900) - `s3-local.nuclide.systems` → `192.168.1.40` (S3 API for local only) ### Service Discovery - `api.nuclide.systems` → `192.168.1.40` (future API gateway) - `web.nuclide.systems` → `192.168.1.40` (general web services) ### Immich - `immich.nuclide.systems` → `192.168.1.40` (Immich web & API) - `immich-api.nuclide.systems` → `192.168.1.40:2283` (Immich API only) ### Paperless-ngx - `pp.nuclide.systems` → `192.168.1.40` (Paperless web) - `pp-api.nuclide.systems` → `192.168.1.40:8000` (Paperless API) ### Home Assistant - `ha.nuclide.systems` → `192.168.1.60` (Home Assistant OS VM 100) - `homeassistant.local` → `192.168.1.60` (mDNS fallback) ## Internal DNS Server Setup ### Option A: Use AdGuard as Forwarding DNS Configure clients to use `192.168.1.2` as their DNS server: 1. Proxmox Host: Edit `/etc/resolv.conf` 2. Docker containers: Add DNS in docker-compose.yml 3. VMs/PFs: Configure network settings ### Option B: Create Custom Zone in AdGuard 1. AdGuard → **DNS Settings** → **Zone Management** 2. Add zone: `nuclide.systems` 3. Add A records for all subdomains with proper IPs 4. Zone file format: ``` @ IN SOA ns1.nuclide.systems. admin.nuclide.systems. ( 1 ; Serial 3600 ; Refresh 1800 ; Retry 604800 ; Expire 86400 ) ; Minimum TTL @ IN NS ns1.nuclide.systems. @ IN A 192.168.1.40 ai IN A 192.168.1.40 chat IN A 192.168.1.40 mcp IN A 192.168.1.40 l IN A 192.168.1.40 ; LiteLLM s3 IN A 192.168.1.40 nc IN A 192.168.1.40 ; NextCloud ``` ## Verification After adding DNS entries: ```bash # Test from any machine on network dig ai.nuclide.systems @192.168.1.2 dig chat.nuclide.systems @192.168.1.2 # Should return: 192.168.1.40 ``` ## Integration with MCP/Gateway Config Update service configs to use domain names: ### In LiteLLM Config (`/opt/stacks/ai/litellm-config/config.yaml`) ```yaml general_settings: proxy_base_url: https://ai.nuclide.systems control_plane_url: https://ai.nuclide.systems ``` ### In Karakeep (`.env`) ```bash OPENAI_BASE_URL=https://ai.nuclide.systems/v1 ``` ### In LobeHub (`.env`) ```bash APP_URL=https://chat.nuclide.systems S3_ENDPOINT=https://s3.nuclide.systems ``` ## Migration Checklist - [ ] Add DNS entries to AdGuard - [ ] Verify resolution: `dig ai.nuclide.systems` - [ ] Update service configs to use domains - [ ] Test HTTPS connectivity - [ ] Remove old hosts file entries (if any) - [ ] Document for team ## Notes - AdGuard runs on **LXC 102** at `192.168.1.2` - All AI services run on `192.168.1.40` - Using same IP for all domains is intentional (single endpoint) - SSL certs are issued by Zoraxy (public domain validation) - DNS-only setup doesn't require HTTP proxy (Zoraxy still handles HTTPS)