Repository files navigation

If you're looking for a way to quickly and easily get up and running with aPi-hole device for your home network, this is theproject for you.

This project is abalenaCloud stack with thefollowing services:

• Pi-hole
• PADD
• Unbound

balenaCloud is a free service to remotely manage and update your Raspberry Pithrough an online dashboard interface, as well as providing remote access to thePi-hole web interface without any additional configuration.

• Raspberry Pi 2/3/4 (Note: this project will not work with the Pi Zero),balenaFin, or NanoPi Neo Air
• 16GB Micro-SD Card (we recommend Sandisk Extreme Pro SD cards)
• Display (any Raspberry Pi display will work for this project)
• Micro-USB cable
• Power supply
• Case (optional)

You can one-click-deploy this project to balena using the button below:

Alternatively, deployment can be carried out by manually creating abalenaCloud account and application,flashing a device, downloading the project and pushing it via thebalena CLI.

Device Variables apply to all services within the application, and can beapplied fleet-wide to apply to multiple devices. If you used theone-click-deploy method, the default environment variables will already be addedfor you to customize as needed.

Additional supported environment variables can be foundhere.

Check out our blog post on how to deploy network-wide ad-blocking with Pi-hole:

https://www.balena.io/blog/deploy-network-wide-ad-blocking-with-pi-hole-and-a-raspberry-pi/

Once your device joins the fleet you'll need to allow some time for it todownload the application and download blocklists.

When it's done you should be able to access the access the app athttp://pihole.local with a default password ofbalena.

On your router or DHCP server assign a static IP reservation (if possible) toyour Pi-hole device, and set your clients DNS to the same IP address.

Documentation for Pi-hole can be found athttps://docs.pi-hole.net/

Note that this project uses thefbcp block.

The PiTFT LCD screensfrom Adafruit (and others) are supported.

In order to use these displays you're required to add additional configurationby setting theFBCP_DISPLAY variable within the dashboard. This variableshould be set to one of the values below:

• adafruit-hx8357d-pitft
• adafruit-ili9341-pitft
• freeplaytech-waveshare32b
• waveshare35b-ili9486
• tontec-mz61581
• waveshare-st7789vw-hat
• waveshare-st7735s-hat
• kedei-v63-mpi3501
• dtoverlay (requiresBALENA_HOST_CONFIG_dtoverlay to be set)

The followingDevice Configurationvariables might be required for proper scaling and resolutions:

Use the environment variablesFONTFACE andFONTSIZE to control the PADD textsize on your display.

Valid font faces are:

• VGA (sizes 8x8, 8x14, 8x16, 16x28 and 16x32)
• Terminus (sizes 6x12, 8x14, 8x16, 10x20, 12x24, 14x28 and 16x32)
• TerminusBold (sizes 8x14, 8x16, 10x20, 12x24, 14x28 and 16x32)
• TerminusBoldVGA (sizes 8x14 and 8x16)
• Fixed (sizes 8x13, 8x14, 8x15, 8x16 and 8x18)

From:https://manpages.debian.org/bullseye/console-setup/console-setup.5.en.html

This project includes an Unbound service providing recursive DNS, but it is notused by default.

Read more about the reasons for using a recursive DNS with Pi-hole here:

https://docs.pi-hole.net/guides/unbound/

Set the following environment variable in your balenaCloud Dashboard to tellPi-hole to forward DNS requests that aren’t blocked to the local Unbound DNSresolver service.

• FTLCONF_dns_upstreams:127.0.0.1#5053;127.0.0.1#5053

Note: For security and footprint reasons, the Unbound container does notallow shell or terminal access via SSH or the balenaCloud console.

Advanced users can change the Unbound configuration by editingunbound.conf ora-records.conf beforepushing the app to balenaCloud.

Included is a Tailscale service in order toaccess your Pi-hole from anywhere.

If you're having trouble getting the project running, submit an issue or post onthe forums athttps://forums.balena.io.

Please open an issue or submit a pull request with any features, fixes, orchanges.