====== TorresVault Local DNS & Domain Architecture ======

This page documents how local DNS, DHCP, hostnames, and subdomains work throughout the TorresVault network.

It covers:
  * Pi-hole local DNS
  * Unifi DHCP domain handing
  * Short-hostname resolution (ex: `pve1` → pve1.torresvault.com)
  * Nginx Proxy Manager integration
  * Internal landing page (in.torresvault.com)
  * Wildcard DNS behavior
  * Local services: Jellyfin, Nextcloud, Kuma, Automation, etc.

----

===== Domain Overview =====

The home lab uses the domain:

**torresvault.com**

DHCP automatically assigns:

  * Primary DNS suffix: **torresvault.com**
  * Search domain list: **torresvault.com**

This means:
  * Typing `pve1` automatically resolves to `pve1.torresvault.com`
  * Typing `next` resolves to `next.torresvault.com`
  * SSH, SMB, and browser URLs work without typing the full domain

----

===== Local DNS Records =====

Pi-hole acts as the authoritative resolver for the internal network.

^ Domain                    ^ IP Address        ^ Purpose                        ^
| in.torresvault.com        | **192.168.1.27**  | Internal homepage/dashboard     |
| pve1.torresvault.com      | **192.168.1.150** | Proxmox Node 1                  |
| pve2.torresvault.com      | **192.168.1.151** | Proxmox Node 2                  |
| torresvault.com           | **192.168.1.99**  | Nginx Proxy Manager (root)      |

These are manually entered into:

**Pi-hole → Local DNS → DNS Records**

----

===== Wildcard DNS ======

A wildcard rule ensures:

*.torresvault.com → 192.168.1.99


This allows any subdomain to hit NPM unless manually overridden.

Examples:

  * `automation.torresvault.com`
  * `photos.torresvault.com`
  * `kuma.torresvault.com`
  * `jellyfin.torresvault.com`
  * `wonderfullymade.style`
  * `next.torresvault.com`

All are routed through Nginx Proxy Manager (NPM).

----

===== Nginx Proxy Manager (NPM) Integration =====

NPM is located at:

  * **192.168.1.99**

NPM handles:

  * Reverse proxying
  * SSL (Let's Encrypt)
  * Wildcard certs (optional)
  * Access control
  * URL rewrites
  * Public/Private service segmentation

Each service has:

  * A Source domain (ex: jellyfin.torresvault.com)
  * A Destination IP+Port (ex: 192.168.1.86:8096)

----

===== Why the wildcard rule works =====

Even though Pi-hole doesn't know the IP of:

`jellyfin.torresvault.com` or `kuma.torresvault.com`

…it **does know**:

*.torresvault.com → 192.168.1.99


Then **NPM** looks at the hostname and routes to the correct service.

----

===== Unifi DHCP Integration =====

Unifi hands out:

DHCP → Domain Name = torresvault.com
DNS Server = 192.168.1.5 (VIP)


Clients automatically adopt:

  * DNS search suffix: torresvault.com  
  * DNS server: Pi-hole VIP  
  * Hostname resolution: pve1, next, jellyfin, etc.

----

===== Short Hostname Resolution =====

Because DHCP gave the domain suffix:

Typing "pve1" converts automatically into:
pve1.torresvault.com


This works for:

  * SSH (`ssh nathan@pve1`)
  * Putty
  * Browser URL bar
  * Ping commands
  * Apps that accept hostnames

----

===== Example Subdomains Used =====

^ Hostname                ^ Public/Internal ^ Resolves To                     ^
| jellyfin.torresvault.com | Internal        | 192.168.1.86:8096 (via NPM)     |
| next.torresvault.com     | Internal        | 192.168.1.75:8080 (via NPM)     |
| kuma.torresvault.com     | Internal        | 192.168.1.141:3001              |
| photos.torresvault.com   | Internal        | 192.168.1.6:2283                |
| automation.torresvault.com | Internal      | 192.168.1.92:5678               |
| status.torresvault.com   | Internal        | 192.168.1.141:3001              |
| torresfamilylights.com   | Internal        | 192.168.1.27:80                 |

----

===== Internal Homepage =====

The internal landing page:

http://in.torresvault.com
→ 192.168.1.27


Contains:

  * Links to every service  
  * IP-overview  
  * Friendly UI for family use  

This page does **not** go through NPM (direct IP mapping).

----

===== Traffic Flow Diagram =====

Client → DNS Query → 192.168.1.5 (VIP Pi-hole)
↓
Pi-hole resolving:
Local DNS? → direct IP
*.torresvault.com? → 192.168.1.99
Else → upstream DNS
↓
NPM at 192.168.1.99
Looks at hostname
Routes traffic to correct backend container/VM


----

===== Benefits =====

  * Local services resolve instantly  
  * Short-hostnames work everywhere  
  * You control the entire internal namespace  
  * New services can be added in seconds  
  * NPM handles SSL automatically  

----