Skip to content

Pi-hole VM Setup ​

The DNS guest runs Pi-hole in Docker on a small Debian VM. Keeping it separate lets DNS remain available when operations tools are updated.

Prepare the physical Proxmox host first. For host-specific accounts, scripted setup, and AI recovery procedures, see Pi-hole VM · Internal Operations.

For another homelab, choose unused guest IDs and addresses, your own gateway and DNS, and storage sized for your workload. Confirm actual inventory and DHCP assignments before creation; a failed ping alone does not prove an address is free.

Guest configuration ​

SettingThis homelab
VM ID / hostname103 / pihole
OSDebian 13 (Trixie)
Resources1 vCPU, 1 GB RAM, 16 GB disk
StorageLocal flash
Address / gateway10.120.40.103/24 / 10.120.40.1
Bridgevmbr0, presenting the Home Lab network
Network deviceVirtIO, with intended Proxmox firewall policy
StartupStart at boot

Create and install the guest ​

Use Create VM in Proxmox with the settings above and a verified Debian 13 amd64 installer ISO. Use VirtIO SCSI for the disk and enable the QEMU Guest Agent option. Match the bridge/VLAN configuration to the host and switch; do not add a tag solely based on the address.

Install a minimal Debian system with SSH server, standard utilities, and a normal sudo-capable administrator. Configure the static address and reserve or exclude it from DHCP. Use a reachable bootstrap DNS resolver during installation; the guest cannot rely on its own Pi-hole service before that service exists. Remove the ISO from the boot path after installation.

The lab's alternative cloud-image creator and guest provisioner remain in the source repository, with their exact use documented internally.

Prepare Debian and Docker ​

Inside the guest:

sh
sudo apt update
sudo apt full-upgrade
sudo apt install ca-certificates curl dnsutils jq openssh-server qemu-guest-agent sudo
sudo systemctl enable --now ssh
sudo systemctl start qemu-guest-agent

Verify the guest agent is enabled on Proxmox too. Install Docker Engine and the Compose plugin from Docker's official Debian repository using the operations guest's Docker steps. Apply its bounded logging configuration before starting application containers. These shared steps apply to Debian 13 here; do not run the operations host's fixed provisioning script on the DNS VM.

Use sudo for Docker or grant your chosen deployment account Docker-group membership and start a fresh login. Docker access is root-equivalent. Keep /docker/pihole and its data on local Linux storage; the guest has no NAS mount dependency.

Configure administrative access ​

Create a normal sudo-capable administrator account during installation or from the initial console. Store its password securely. Install only your intended public SSH key while preserving existing keys, then prove a fresh key-authenticated session before disabling password and keyboard-interactive authentication. Inspect sshd -T, validate with sshd -t, and reload ssh.service while keeping the initial session and Proxmox console available.

For a new guest with a proven non-root administrative account, an early SSH drop-in can use:

text
PubkeyAuthentication yes
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no

Verify a new key login succeeds and password-based login is rejected. The exact lab usernames and reviewed policy files are internal. Do not apply a root-login restriction before a non-root administrator and recovery path work.

Deploy DNS before client cutover ​

Follow Pi-hole setup to configure the environment, start the stack, add filtering policy, and set up HTTPS administration. Verify DNS over UDP and TCP from every intended client network before changing UniFi DHCP. Keep UniFi as the DHCP server.

Do not advertise this DNS server to clients until resolution works. Verify the chosen upstream resolvers remain reachable after cutover and test a client lease renewal.

Backups and startup checks ​

Set Start at boot deliberately and preserve the physical host's coordinated startup behavior. Configure a protected off-host Proxmox backup with a schedule and retention appropriate to the guest, then test restoration without creating a duplicate active address or identity.

After initial setup or a controlled reboot, confirm network configuration, DNS, key-only access, service health, and the application's primary function. Keep the Proxmox guest console as an out-of-band recovery path. Inspect active backup and storage tasks before maintenance; avoid hard power removal.