Home Lab Series Part 4: Pi-hole & Homepage (The First Apps)

The engine is running. Now let's take it for a drive. In Part 3, we installed Portainer. Today, we will use it to deploy the "Holy Grail" of home networking: Network-wide Ad Blocking.

We are also going to install a dashboard called Homepage. As you add more services to your lab, remembering IP addresses and port numbers becomes impossible. Homepage gives you a beautiful "Start Menu" for your server.

Step 1: Understanding Stacks

We could install apps by typing long commands into the terminal, but that is messy. The professional way is to use Stacks (also known as Docker Compose).

A Stack is just a text file (YAML) that lists instructions. It says: "I want this app, with these settings, saved in this folder." If you ever move to a new server, you just copy the text file, and your entire setup moves with you.

Step 2: Installing Pi-hole

Let's block some ads.

1. Open Portainer (`https://[YOUR-IP]:9443`).
2. Click Local -> Stacks -> + Add stack.
3. Name the stack: pihole.
4. Paste the following code into the Web Editor:

services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "8080:80"  # We map host 8080 to container 80 to avoid conflicts
    environment:
      TZ: 'America/New_York'
      WEBPASSWORD: 'securepassword123' # Change this!
    volumes:
      - './etc-pihole:/etc/pihole'
      - './etc-dnsmasq.d:/etc/dnsmasq.d'
    restart: unless-stopped

Click Deploy the stack at the bottom. It will take a minute to download.

Accessing Pi-hole

Once it says "Deployed," open a new browser tab and go to:

http://[YOUR-IP]:8080/admin

You should see the Pi-hole dashboard! Right now, it says "0 Queries" because no devices are using it yet.

Step 3: The Router Config (Crucial)

Installing Pi-hole doesn't magically block ads. You must tell your router to send traffic to it.

Step 4: Installing "Homepage"

Now let's build a dashboard so we can get to Portainer and Pi-hole easily.

1. Go back to Portainer -> Stacks -> + Add stack.
2. Name the stack: homepage.
3. Paste this code:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - ./config:/app/config # Saves your config files to the host
      - /var/run/docker.sock:/var/run/docker.sock # Allows it to see other containers
    restart: unless-stopped

Deploy the stack. Once finished, visit http://[YOUR-IP]:3000.

You will see the default dashboard. To customize it (add your own links), you need to edit the YAML files located in the /config folder on your server. This is your first step into "Configuration as Code!"

Troubleshooting Common Errors

Conclusion

You have successfully deployed a functional network appliance (Pi-hole) and a frontend dashboard (Homepage). Your network is now faster, cleaner, and looks cooler.

Coming Up in Part 5: We will tackle Media Management. It is time to replace Netflix with Jellyfin.