↓ Skip to main content
Zac Trolley
  1. Building Your Own Server/

Pi-hole - Network-Wide Ad Blocker

·848 words·4 mins

Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking ads, trackers, and malicious websites before they reach your devices. By running Pi-hole on your own server, you protect all devices on your network without needing to install apps on each one.

Pi-Hole

Why Pi-hole:

  • Network-Wide Protection: Blocks ads on all devices - phones, tablets, smart TVs, gaming consoles. Your network, your rules. No corporation tracks your browsing habits.
  • Privacy First: No data is sent to third parties; everything stays on your network. Stop advertisers from building profiles about your online activity
  • Fast Browsing: Blocks ads and trackers, making web pages load faster
  • Parental Controls: Block inappropriate content for your family

Resources
#

Installation Prep
#

Before installing Pi-hole, ensure you have the following ready:

Time to Complete
#

  • Total Time: ~20 minutes
    • 5 min: File system prep
    • 5 min: Docker setup
    • 5 min: Download Pi-hole image
    • 5 min: Router configuration
  • Difficulty: Beginner
  • Note: Pi-hole will become your network’s DNS server. Ensure you can access your router’s admin panel.

Installation
#

Step 1: File System Prep
#

We need to create the directories to keep the docker compose file and Pi-hole configuration.

Create the Pi-hole directory

mkdir -p ~/docker/pihole/

Create the folders where your data will live:

mkdir -p ~/docker/pihole/{etc,libdnsmasq}

This creates the following structure:

/home/USER/docker/pihole/etc/          # Pi-hole configuration
/home/USER/docker/pihole/libdnsmasq/   # DNSMasq configuration

Step 2: Docker Setup
#

Make sure you are in your Pi-hole directory:

cd ~/docker/pihole

To double check you are in the right place, type pwd to see your current directory.

Create the docker compose.yaml file:

sudo nano docker compose.yaml

Step 3: docker compose file
#

Copy the following text into the docker compose file:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"
    environment:
      - TZ=America/Edmonton
      - WEBPASSWORD=your_secure_password
    volumes:
      - ./etc:/etc/pihole
      - ./libdnsmasq:/etc/dnsmasq.d
    restart: unless-stopped

Important: Replace your_secure_password with a strong password for the Pi-hole web interface.

Save and exit the file by pressing Ctrl+X and saying Y to save.

Step 4: Start Pi-hole
#

Now you can download and start Pi-hole:

sudo docker compose pull
sudo docker compose up -d

Once the pull is complete, verify the container is running:

docker ps

You should see pihole running.

Initial Setup and Configuration
#

Step 1: Access Pi-hole Web Interface
#

Open your browser and navigate to:

http://192.168.99.1/admin

This is the IP address of your Linux Mint machine where Pi-hole is installed.

If you aren’t sure about your IP address or ports, refer to the networking guide or other internet sources. Understanding networking is critical to running and maintaining your own services.

Log in with the password you set in the docker compose file.

Step 2: Change Router DNS Settings
#

To make Pi-hole your network’s DNS server, you need to change your router’s DNS settings:

  1. Access your router’s admin panel (usually http://192.168.1.1 or check your router’s documentation)
  2. Log in with your router credentials
  3. Find the DHCP/DNS Settings section
  4. Change Primary DNS to 192.168.99.1 (your Pi-hole server)
  5. Change Secondary DNS to a public DNS like 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare)
  6. Save the settings

Alternative: Instead of changing router settings, you can configure individual devices to use Pi-hole as their DNS server.

Step 3: Test Pi-hole
#

  1. Open a web browser on any device connected to your network
  2. Visit a site with ads (e.g., youtube.com)
  3. You should see fewer ads than before
  4. Check the Pi-hole dashboard at http://192.168.99.1/admin to see blocked queries

Usage
#

Web Interface
#

The Pi-hole web interface (http://192.168.99.1/admin) provides:

  • Dashboard: Overview of blocked queries, top domains, recent activity
  • Query Log: View all DNS queries in real-time
  • Block Lists: Manage which domains are blocked
  • Tools: Flush DNS cache, test DNS resolution
  • Settings: Configure Pi-hole behavior

Common Tasks
#

View Blocked Queries:

  • Check the dashboard for real-time statistics
  • Use the Query Log to see detailed records

Add/Remove Domains:

  • Go to Block Lists to manage lists
  • Use White List to allow previously blocked domains
  • Use Black List to block additional domains

Flush DNS Cache:

  • Go to Tools > Flush DNS Cache

Maintenance
#

Updates
#

Update Pi-hole and Docker images:

cd ~/docker/pihole
sudo docker compose pull
sudo docker compose up -d

Block List Management
#

Regularly update your block lists:

  1. Go to Settings > Blocklists
  2. Click Update Gravity to refresh all lists

Troubleshooting
#

Pi-hole Not Blocking Ads
#

  1. Check that your devices are using Pi-hole as DNS
  2. Flush DNS cache on your devices
  3. Check the Query Log to see if queries are being made to Pi-hole

Web Interface Not Accessible
#

  1. Verify Pi-hole container is running: docker ps
  2. Check if port 80 is already in use: sudo netstat -tulpn | grep :80
  3. Restart Pi-hole: sudo docker compose restart

DNS Resolution Issues
#

  1. Check your router’s DNS settings
  2. Verify Pi-hole is running: sudo docker ps
  3. Test DNS resolution: nslookup google.com 192.168.99.1