TrueNAS AppsTrueNAS Apps: Tutorials
Application maintenance is independent from TrueNAS version release cycles.
App versions, features, options, and installation behavior at time of access might vary from documented tutorials and UI reference.

Pi-Hole

This Community App article provides installation instructions using the legacy TrueNAS Applications screen. TrueNAS 23.10 (Cobia) introduces new Installed and Discover screens for applications. See Apps and Applications Screens to learn how to install applications using these screens.

TrueNAS includes the ability to run Docker containers using Docker Compose.

What is Docker? Docker is an open platform for developing, shipping, and running applications. Docker enables the separation of applications from infrastructure through OS-level virtualization to deliver software in containers.

Always read through the Docker Hub page for the container you are considering installing so that you know all of the settings that you need to configure. To set up a Docker image, first determine if you want the container to use its own dataset. If yes, create a dataset for host volume paths before you click Launch Docker Image.

We welcome community contributions to keep this documentation current! Click Edit Page in the top right corner to propose changes to this article. See Updating Content for more information.

Installing Pi-hole Application

If you want to create a dataset for Pi-hole data storage, you must do this before beginning the Pi-hole application install.

When you are ready to create a container, click Apps to open the Applications screen, then click on Available Applications. Locate the pihole widget and click Install on the widget.

AvailableApplicationsScreen

Fill in the Application Name and click Version to verify the default version is the only, and most current version.

AppPiHoleApplicationNameAndVersion

Enter the password to use for the administrative user in Admin password in the Container Environment Variables section. The password entered can not be edited after you click Save. Adjust the Configure timezone setting if it does not match where your TrueNAS is located.

To add the WEBPASSWORD environment variable, click Add for Pihole Environment to add a block of environment variable settings. Enter WEBPASSWORD in Name, then a secure password like the example the one used, s3curep4$$word.

AppPiHoleConfigurationSettings

Scroll down to the Storage settings. Select Enable Custom Host Path for Pihole Configuration Volume to add the Host Path for Pihole Configuration Volume field and dataset browse option. Click the arrow to the left of /mnt and at each dataset to expand the tree and browse to the dataset and directory paths you created before beginning the container deployment. Pi-hole uses volumes store your data between container upgrades.

You need to create these directories in a dataset on TrueNAS before you begin installing this container. Create directories in a dataset on TrueNAS, before you begin installing the container.

To create a directory, open the Linux CLI and enter mkdir path="/path/to/directory" or if you have a share created on your system with access to the dataset use it to create a directory.

AppPiHoleStorageSettings

Click Add to display setting options to add extra host path volumes to the container if you need them.

Enter any Networking settings you want to use or customize. TrueNAS adds the port assignments Pi-hole requires in the Web Port for pihole, DNS TCP Port for pihole, and DNS UDP Port for pihole fields. TrueNAS requires setting all Node Ports above 9000. Select Enable Host Network to add host network settings. Click Add for DNS Options to add a block of DNS settings if you want to configure DNS options.

AppPiHoleNetworkingSettings

Click Add for DNS Options if you want to configure DNS for your pod. Select Enable Pod resource limits if you want to limit the CPU and memory for your Pi-hole application.

AppPiHoleDNSAndResourceLimitsSettings

Click Save. TrueNAS deploys the container. If correctly configured, the Pi-Hole widget displays on the Installed Applications screen.

When the deployment is completed the container becomes active. If the container does not automatically start, click Start on the widget. Clicking on the App card reveals details on the app.

With Pi-hole as our example we navigate to the IP of our TrueNAS system with the port and directory address :9080/admin/.

PiHoleRunning