3 min read

Simplifying Self-Hosting: Enabling DNS Resolution for Containerized Services with Pi-hole

Introduction

In a self-hosted environment, managing DNS resolution is crucial for seamless communication between services. If you're running multiple containerized services on the same machine, such as Nextcloud, a mail server, and Pi-hole as your internal DNS. This guide focuses on how to configure your containerized services to utilize Pi-hole for DNS resolution, enabling services like Nextcloud to connect to your mail server.

Prerequisites

This guide assumes you have the following already set up:

  • Pi-hole running as your DNS server.
  • Multiple containerized services (e.g., Nextcloud, Ghost, Mail Server) on the same machine.
  • Cloudflare or another DNS service for external DNS resolution.

Step-by-Step Guide

Configuring Local DNS Entries in Pi-hole

To ensure your services can communicate using domain names rather than IP addresses, you need to add local DNS records in Pi-hole.

Add Local DNS Records

  1. Access the Pi-hole admin interface by navigating to http://pi.hole/admin in your browser.
  2. Go to Local DNS > DNS Records.
  3. Add a DNS entry for your mail server. For example:
    • Mail Server: mail.example.com -> [local IP of the Mail Server container]

This setup ensures that when a service within your network queries mail.example.com, Pi-hole resolves it to the local IP of your mail server.

Setting Up a Bridge Network for Containers

To manage your container network effectively, you'll create a bridge network with a specific IP range and assign static IP addresses to your containers.

Creating the Bridge Network

Define an external bridge network in your Docker Compose file:

networks:
  my_bridge_network:
    external: true

Create the network with a defined subnet:

docker network create --subnet=172.19.0.0/24 my_bridge_network

Configuring Pi-hole with a Static IP

In your docker-compose.yml for Pi-hole, assign a static IP within the created subnet:

services:
  pihole:
    image: pihole/pihole:latest
    container_name: pihole
    networks:
      my_bridge_network:
        ipv4_address: 172.19.0.3
    # other configurations

networks:
  my_bridge_network:
    external: true

Configuring Other Services to Use Pi-hole

Now, configure your other services (e.g., Nextcloud, Ghost) to use Pi-hole for DNS resolution by specifying the DNS server and assigning static IPs.

Sample Configuration for Nextcloud:

services:
  nextcloud:
    image: nextcloud
    container_name: nextcloud
    dns:
      - 172.19.0.3
      - 1.1.1.1
    networks:
      my_bridge_network:
        ipv4_address: 172.19.0.4
    # other configurations

networks:
  my_bridge_network:
    external: true

Sample Configuration for Ghost:

services:
  ghost:
    image: ghost
    container_name: ghost
    dns:
      - 172.19.0.3
      - 1.1.1.1
    networks:
      my_bridge_network:
        ipv4_address: 172.19.0.5
    # other configurations

networks:
  my_bridge_network:
    external: true

Restarting the Containers

After updating the docker-compose.yml files, restart your containers to apply the changes:

docker-compose down
docker-compose up -d

Verifying DNS Resolution

Once your containers are configured to use Pi-hole, you can test the DNS resolution by trying to access the services within your application. Since nslookup or dig might not be available in your containers, ensure the service configurations are correct and try accessing the service domains from within the applications. If your service has nslookup, you can do:

docker exec -it nextcloud /bin/bash
nslookup mail.example.com

You should see the local IP address of your mail server returned. This confirms that Nextcloud can resolve the mail server's address using Pi-hole.

Configuring Services to Use the Mail Server

With DNS resolution set up, configure your services to use your mail server for sending emails. For instance, in Nextcloud, you would set the SMTP server to mail.example.com. Other services might require setting environment variables or specifying SMTP details in the application settings.

Troubleshooting Common Issues

DNS Resolution Failures

  • Ensure the DNS entries in Pi-hole are correct.
  • Verify that the containers are configured to use Pi-hole as their DNS server.

Service Connectivity Problems

  • Check that the services are running and accessible using their local IP addresses.
  • Ensure there are no network or firewall rules blocking communication between the containers.

Conclusion

Using Pi-hole for internal DNS resolution in a self-hosted environment simplifies service interactions. By configuring your containerised services to use Pi-hole, you ensure reliable and efficient communication within your local network. This setup allows services like Nextcloud to easily connect to your mail server, enhancing the overall functionality and reliability of your self-hosted ecosystem.

Happy self-hosting! If you have any questions, feel free to comment below, and I'll be happy to help.

Don't forget to subscribe, it's free (and new for me)!

Shashi Ranjan

Shashi Ranjan

India