{"id":15,"date":"2023-09-16T08:31:35","date_gmt":"2023-09-16T13:31:35","guid":{"rendered":"https:\/\/wp.jkhayer.us\/?p=15"},"modified":"2023-09-16T08:36:50","modified_gmt":"2023-09-16T13:36:50","slug":"running-pi-hole-as-a-docker-container","status":"publish","type":"post","link":"https:\/\/wp.jkhayer.us\/?p=15","title":{"rendered":"Running Pi-Hole as a Docker Container"},"content":{"rendered":"\n

This tutorial will show you how to install and run Pi-Hole as a Docker container.<\/p>\n\n\n\n

\"Pi-Hole<\/figure>\n\n\n\n

Pi-Hole is a software that act as your DNS provider to actively block internet ads and trackers. It does this by filtering the DNS requests and sending any blocked domains into a blackhole, so the request is never completed.<\/p>\n\n\n\n

Another cool thing about Pi-Hole is that it can also work well to monitor your network traffic, as you can set it to log any DNS requests that the server receives.<\/p>\n\n\n\n

While this software is perfect for devices like the Raspberry<\/a> Pi, you can install it on any Linux machine. Or, when using Docker, you can even run Pi-Hole on a Windows device.<\/p>\n\n\n\n

You can run Pi-Hole on your devices in many ways, but one of the easiest is to use Docker. The advantage of using Docker is that everything you need is set up within the container.<\/p>\n\n\n\n

Please note that we tested the following steps for installing Pi-Hole through a Docker container on an Ubuntu system. However, they should work fine on any system where you can install \u201cDocker\u201d and \u201cDocker Compose\u201d.<\/p>\n\n\n\n

<\/p>\n\n\n\n

Preparing your System to Run Pi-Hole as a Container<\/h2>\n\n\n\n

These first few steps will get your Linux system set up to run Pi-Hole through a Docker container. If you already have Docker installed on your system, you can skip to the \u201cInstalling the Pi-Hole Docker Container<\/a>\u201d section.<\/p>\n\n\n\n

1.<\/strong> If you are running a Debian-based operating system such as Ubuntu, you will need to update the package list cache before we can install the software needed to run Pi-Hole.<\/p>\n\n\n\n

You can update the package list by using the following command.<\/p>\n\n\n\n

<\/pre>\n\n\n\n
sudo apt updateCopy <\/code><\/pre>\n\n\n\n
2.<\/strong> The only package we need to get Pi-Hole running with Docker is the Docker runtime.<\/p>\n\n\n\n
This process is straightforward as long as your operating system has Docker available in its main package repository. Popular operating systems like Ubuntu already have Docker available in its repository.<\/p>\n\n\n\n
If it is available, you can install Docker-compose by using the relevant command below in the terminal.<\/p>\n\n\n\n
Systems Using the apt Package Manager (Debian, Ubuntu, Raspberry Pi OS, Linux Mint, etc.)<\/strong><\/p>\n\n\n\n
For Debian-based systems such as Ubuntu, you can use the following command.<\/p>\n\n\n\n
<\/pre>\n\n\n\n
\n
sudo apt install docker-compose<\/code>Copy<\/a><\/pre>\n<\/blockquote>\n\n\n\n
Systems Using the dnf Package Manager (RHEL 8+, Fedora 22+, CentOS 8+, etc)<\/strong><\/p>\n\n\n\n
If you are using a system that uses the DNF package manager, you can run the command below.<\/p>\n\n\n\n
sudo dnf install docker-compose<\/code>Copy<\/a><\/pre>\n\n\n\n
Systems Using the yum Package Manager (RHEL7, Fedora 21, CentOS 7, etc)<\/strong><\/p>\n\n\n\n
For systems that use the yum Package manager, you can use the below command.<\/p>\n\n\n\n
sudo yum install docker-compose<\/code>Copy<\/a><\/pre>\n\n\n\n
3.<\/strong> That is all the software you need on your Linux system to run Pi-Hole within a Docker container.<\/p>\n\n\n\n
Any additional software that is needed will all be stored within the container. This greatly simplifies getting Pi-Hole running on Linux-based systems such as Ubuntu.<\/p>\n\n\n\n
Installing the Pi-Hole Docker Container<\/h2>\n\n\n\n
This section will show you the process of installing Pi-Hole as a Docker container on your Linux-based system. All we need to do within this section is to write a \u201cdocker-compose<\/code>\u201d configuration file.<\/p>\n\n\n\n
This file tells Docker what containers it needs to download and what ports it needs to open.<\/p>\n\n\n\n
Creating a Directory for Pi-Hole<\/h3>\n\n\n\n
1.<\/strong> Start by creating a directory where you will store the configuration file for the Pi-Hole docker container.<\/p>\n\n\n\n
We will do this by using the mkdir command<\/a> to create a directory called \u201cpihole<\/code>\u201d in our user\u2019s home directory.<\/p>\n\n\n\n
mkdir ~\/pihole<\/code>Copy<\/a><\/pre>\n\n\n\n
2.<\/strong> Let us move into our newly created directory by using the cd command<\/a>.<\/p>\n\n\n\n
cd ~\/pihole<\/code>Copy<\/a><\/pre>\n\n\n\n
Writing the Docker-Compose Configuration File<\/h3>\n\n\n\n
3.<\/strong> Our next step is writing the \u201cdocker-compose.yml<\/code>\u201d file. This file is where we will define the Pi-Hole docker container and the options we want passed to the container.<\/p>\n\n\n\n
nano docker-compose.yml<\/code>Copy<\/a><\/pre>\n\n\n\n
4.<\/strong> Within this file, you will want to enter the following lines. We will explain the pieces you may want to modify shortly.<\/p>\n\n\n\n
version: \"3\"\n\nservices:\n  pihole:\n    container_name: pihole\n    image: pihole\/pihole:latest\n    ports:\n      - \"53:53\/tcp\"\n      - \"53:53\/udp\"\n      - \"67:67\/udp\"\n      - \"80:80\/tcp\"\n    environment:\n      TZ: 'America\/Chicago'\n      # WEBPASSWORD: 'set a secure password here or it will be random'\n    volumes:\n      - '.\/etc-pihole:\/etc\/pihole'\n      - '.\/etc-dnsmasq.d:\/etc\/dnsmasq.d'\n    cap_add:\n      - NET_ADMIN\n    restart: unless-stopped<\/code>Copy<\/a><\/pre>\n\n\n\n
Configuring the Pi-Hole Configuration File<\/h3>\n\n\n\n
5.<\/strong> Before you save this file, there are three Docker options that you will want to reconfigure for Pi-Hole to suit your setup better.<\/p>\n\n\n\n
Setting the Password for the Pi-Hole Web Interface<\/h4>\n\n\n\n
Out of all the things to configure, you will want to set a secure password before running the Pi-Hole container. Pi-Hole will randomly generate the password if you don\u2019t set a value.<\/p>\n\n\n\n
Begin by looking for the following line within the configuration file.<\/p>\n\n\n\n
      # WEBPASSWORD: 'set a secure password here or it will be random'<\/code>Copy<\/a><\/pre>\n\n\n\n
Replace with the following, switching out \u201cSECUREPASSWORD<\/code>\u201d with a secure password of your own. Try and use letters, numbers, and symbols.<\/p>\n\n\n\n
If you want to generate secure passwords and store them securely, we recommend you check out the NordPass password manager<\/a> (Affiliate link).<\/p>\n\n\n\n
      WEBPASSWORD: 'SECUREPASSWORD'<\/code>Copy<\/a><\/pre>\n\n\n\n
Configuring the Web Interface Port of Pi-Hole<\/strong><\/h4>\n\n\n\n
By default, we will set up the Docker container so Pi-Hole will be accessible through port80<\/code> on your system. This could be problematic if you already have something operating on port 80<\/code>.<\/p>\n\n\n\n
To change this, you will want to find the following line and change the number on the left side of the colon (:<\/code>).<\/p>\n\n\n\n
      - \"80:80\/tcp\"<\/code>Copy<\/a><\/pre>\n\n\n\n
For example, to change the port to \u201c8080<\/code>\u201c, you would replace that line with the following.<\/p>\n\n\n\n
      - \"8080:80\/tcp\"<\/code>Copy<\/a><\/pre>\n\n\n\n
Setting the Time Zone for the Pi-Hole Docker Container<\/strong><\/h4>\n\n\n\n
By default, the Pi-Hole docker container has been configured to use the \u201cChicago<\/code>\u201d time zone. It is possible, however, to adjust this to your local time zone.<\/p>\n\n\n\n
You can find a list of valid time zone values on Wikipedia<\/a>. The value you want to use is in the \u201cTZ database name\u201d column.<\/p>\n\n\n\n
To adjust the time zone, find the following line within the file.<\/p>\n\n\n\n
      TZ: 'America\/Chicago'<\/code>Copy<\/a><\/pre>\n\n\n\n
Adjust this value to match your time zone. For example, for Hobart, Australia, we would utilize the line below.<\/p>\n\n\n\n
      TZ: 'Australia\/Hobart'<\/code>Copy<\/a><\/pre>\n\n\n\n
Saving the Docker-Compose File<\/h3>\n\n\n\n
6.<\/strong> Once you have made the above changes to the file, save and quit by pressing CTRL<\/kbd> + X<\/kbd>, followed by Y<\/kbd>, then the ENTER<\/kbd> key.<\/p>\n\n\n\n
Disabling the Systemd-Resolve Service (Ubuntu Only)<\/h3>\n\n\n\n
7.<\/strong> If you are using an Ubuntu to run the Pi-Hole Docker container, you may need to disable the Systemd-resolve service.<\/p>\n\n\n\n
The operating system uses this service to provide network name resolution. As Pi-Hole will want to operate on the same part the resolve service does, we need to disable it.<\/p>\n\n\n\n
Start by stopping the systemd-resolve service by using the following command.<\/p>\n\n\n\n
sudo systemctl stop systemd-resolve<\/code>Copy<\/a><\/pre>\n\n\n\n
8.<\/strong> With the service stopped, you will also want to disable it by using the command below.<\/p>\n\n\n\n
Disabling the service will stop Ubuntu from starting it back up the next time you restart your device.<\/p>\n\n\n\n
sudo systemctl disable systemd-resolve<\/code>Copy<\/a><\/pre>\n\n\n\n
9.<\/strong> With the \u201csystemd-resolve<\/code>\u201d service now disabled, our next step is to modify the \u201c\/etc\/resolv.conf<\/code>\u201d file to point to a different nameserver. By default, the nameserver will be configured to the systemd service.<\/p>\n\n\n\n
Use the command below to begin modifying the configuration file.<\/p>\n\n\n\n
sudo nano \/etc\/resolv.conf<\/code>Copy<\/a><\/pre>\n\n\n\n
10.<\/strong> You will want to find and replace the following line within this file.<\/p>\n\n\n\n
nameserver 127.0.0.53<\/code>Copy<\/a><\/pre>\n\n\n\n
Replace it with the following. This changes the nameserver to Cloudflare\u2019s 1.1.1.1 service.<\/p>\n\n\n\n
nameserver 1.1.1.1<\/code>Copy<\/a><\/pre>\n\n\n\n
11.<\/strong> Once you have made changes to this file, save and quit by pressing CTRL<\/kbd> + X<\/kbd>, followed by Y<\/kbd>, then the ENTER <\/kbd>key.<\/p>\n\n\n\n
Starting the Pi-Hole Docker Container<\/h3>\n\n\n\n
12.<\/strong> We can finally start up Pi-Hole\u2019s Docker container on our Linux system.<\/p>\n\n\n\n
All you need to do now is run the following command within the terminal.<\/p>\n\n\n\n
sudo docker-compose up -d<\/code>Copy<\/a><\/pre>\n\n\n\n
Please note this process can take a couple of minutes, depending on your device\u2019s internet connection.<\/p>\n\n\n\n
Accessing the Pi-Hole Web Interface<\/h2>\n\n\n\n
Now that we have the Pi-Hole docker container up and running on your system, we can proceed to use its web interface.<\/p>\n\n\n\n
This web interface allows you to control all aspects of Pi-Hole on your system, so you won\u2019t have to mess around with configuration files.<\/p>\n\n\n\n
1.<\/strong> Before we begin, you will need to know the IP address of your device so that you can access the web interface.<\/p>\n\n\n\n
The easiest way to get the local IP address is to use the hostname command.<\/p>\n\n\n\n
hostname -I<\/code>Copy<\/a><\/pre>\n\n\n\n
2.<\/strong> With your local IP address, you will want to go to the following within your web browser.<\/p>\n\n\n\n
Ensure you replace \u201cIPADDRESS<\/code>\u201d with the IP you got in the previous step.<\/p>\n\n\n\n
http:\/\/IPADDRESS\/admin<\/code>Copy<\/a><\/pre>\n\n\n\n
If you changed the port away from \u201c80<\/code>\u201c, you need to insert the port like shown below.<\/p>\n\n\n\n
http:\/\/IPADDRESS:PORT\/admin<\/code>Copy<\/a><\/pre>\n\n\n\n
3.<\/strong> You should now be greeted with the login page for Pi-Hole.<\/p>\n\n\n\n
To log in, you must type in the password (1.<\/strong>) you set when writing the Docker configuration file earlier.<\/p>\n\n\n\n
With your password typed in, click<\/kbd> the \u201cLog In<\/code>\u201d button (2.<\/strong>)<\/p>\n\n\n\n
\"Pi-Hole<\/figure>\n\n\n\n
4.<\/strong> You now have access to the Pi-Hole dashboard running from within the Docker container.<\/p>\n\n\n\n
\"Pi-Hole<\/figure>\n\n\n\n
5.<\/strong> With access to the dashboard, now is a good time to start changing your device\u2019s DNS to use Pi-Hole.<\/p>\n\n\n\n
We won\u2019t be covering how exactly to do this in this guide. However, we have a guide that shows you how to change the DNS servers on Ubuntu.<\/p>\n\n\n\n
When setting the DNS servers, you must use the IP belonging to the device you are running Pi-Hole on.<\/p>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
This tutorial shows you how to run Pi-Hole within a docker container on a Linux system.<\/p>\n\n\n\n
Pi-Hole is a neat software that allows you to run a network-wide ad blocker easily. It works by handling your DNS requests and blocking domain names associated with ads.<\/p>\n\n\n\n
Please comment below if you have any issues getting Pi-Hole to work within Docker.<\/p>\n\n\n\n
We also have numerous other tutorials showing what\u00a0you can achieve with Ubuntu<\/a>.<\/p>\n\n\n\n
<\/p>\n\n\n\n
<\/p>\n\n\n\n
<\/code><\/pre>\n\n\n\n
<\/h2>\n\n\n\n
<\/h2>\n","protected":false},"excerpt":{"rendered":"
This tutorial will show you how to install and run Pi-Hole as a Docker container. Pi-Hole is a software that<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-15","post","type-post","status-publish","format-standard","hentry","category-tutorials"],"_links":{"self":[{"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=\/wp\/v2\/posts\/15","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=15"}],"version-history":[{"count":7,"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=\/wp\/v2\/posts\/15\/revisions"}],"predecessor-version":[{"id":23,"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=\/wp\/v2\/posts\/15\/revisions\/23"}],"wp:attachment":[{"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=15"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=15"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wp.jkhayer.us\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=15"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}