Table of contents

• Overview
• Features
• Supported Platforms
• Upcoming features
• Support
• Installation
  • Pre-Requisites
  • Installation Options
  • Configuration
  • Where to generate a Pi-hole App Password
  • AdGuard Home credentials
  • Personalize your Widget
  • Running the widget
• Testing
• Distribution
• Credits
• License

Overview

DNSBlocker Widgets for Desktop (Pi-hole + AdGuard Home)

DNSBlocker Widgets is a desktop widget for monitoring and controlling your DNS blocker (Pi-hole or AdGuard Home).

It is developed with JavaFX, and uses the framework TilesFX.

Screen Shots

Square

Horizontal

Features

Core Features

• Live stats from Pi-hole / AdGuard Home - Real-time monitoring of your DNS blocker.
• Dual DNS blocker support - Monitor and control two DNS blockers simultaneously (e.g., primary and backup).
• Modern, customizable widgets - Beautiful TilesFX-based interface.
• Great summary - All your DNS blocker stats combined in one place.
• Last blocked domain - See what was blocked most recently.
• Gravity update status - Shows when gravity was last updated.

Themes & Customization

• Dark and Light themes - Switch between elegant dark mode and clean light mode.
• Adjustable widget sizes - Small, Medium, Large, XXL, or Full Screen.
• Multiple layouts - Choose between Horizontal and Square layouts.
• Simple configuration interface - Easy right-click access to settings.

System Tray Integration

• Hide to tray - Minimize the widget to system tray for a clean desktop.
• Tray context menu - Quick access to Show, Hide, Settings, and Exit.
• Double-click to restore - Easily bring back the widget from tray.

Pi-hole Control

• Enable/Disable Pi-hole - Toggle DNS blocking directly from the widget.
• Refresh on demand - Manual refresh option via right-click menu.
• HTTP/HTTPS support - Connect to your Pi-hole using secure or standard protocols.

Cross-Platform

• Windows, macOS, and Linux support - Native packages for all major platforms.
• Portable distribution - Windows portable ZIP requires no installation.
• No Java installation required - Java runtime bundled with all packages.

Supported Platforms

All installers include bundled Java runtime - no separate installation required!

Upcoming features

• Additional themes and color schemes.
• Update Gravity List
• Export configs

Donation

All donations are welcome and any amount of money will help me to maintain this project :)

Installation

Pre-Requisites

For End Users (using installers): - None! Java runtime is bundled with all installers. - Last version of Pi-hole running on your network.

For Developers (building from source): - Java 25 JDK (set JAVA_HOME to your JDK 25 installation). - Git (for cloning the repository). - Platform-specific build tools (see DISTRIBUTION.md for details).

Configuration

The widget automatically sets its configuration to the default pi-hole local address if that doesn't work, open the configuration interface by right clicking on the widget then click on Settings.

DNS 1 Settings (Primary DNS Blocker)

Select your Platform (Pi-hole or AdGuard Home), then enter the IP Address, Port, and your credentials:

• Pi-hole: generate an App Password in the Pi-hole web UI and enter it as the password or your authentication password.
• AdGuard Home: enter your Username and Password (Basic Auth).

DNS 2 Settings (Optional Secondary DNS Blocker)

You can optionally configure a second DNS blocker (e.g., a backup Pi-hole or a secondary AdGuard Home instance). The widget will combine statistics from both blockers and display aggregated data. Toggle actions (enable/disable blocking) will apply to both DNS blockers simultaneously.

Leave DNS 2 empty if you only have one DNS blocker.

Click Apply.

Configuration file location

Your settings are stored in a settings.json file under your user home directory:

• Windows: %USERPROFILE%\\DNSBlocker Widget\\settings.json
• Linux/macOS: ~\/DNSBlocker Widget\/settings.json

On startup, the app will create this file only if it is missing (it will not overwrite an existing settings.json).

Where to generate a Pi-hole App Password

Enable Expert Settings

then click on configure app password

AdGuard Home credentials

For AdGuard Home, use the same Username / Password you use to log into the AdGuard Home web interface.

Personalize your widget

You can set your Widget size, layout, theme, and refresh behavior in the Widget Settings panel.

Note: settings marked with (*) in the UI (typically Size and Layout) require a restart to take effect.

Available options: - Size: Small, Medium, Large, XXL, Full Screen - Layout: Horizontal, Square - Theme: Dark, Light - Refresh intervals (seconds): - Status update (s) - Fluid update (s) - Active update (s) - Top domains update (s) - Top domains count: how many domains to show in the “Top X Blocked” tile

Installation Options

Option 1: Download Pre-built Installers (Recommended)

Download the latest installer for your platform from the Releases page:

• Windows: Download the Windows portable .zip, unzip it, and run DNSBlocker Widgets.exe
• macOS: Download and run the .pkg installer
• Linux (Debian/Ubuntu): Download the .deb file and install with: bash sudo dpkg -i dnsblocker-widgets_*.deb
• Linux (Fedora/RHEL): Download the .rpm file and install with: bash sudo rpm -i dnsblocker-widgets-*.rpm

All packages include the bundled Java runtime - no separate Java installation needed!

Option 2: Build from Source

All builds are done through Gradle commands directly:

# Clone the repository
git clone https://github.com/FoKss-LTS/PiHoleWidgets.git
cd PiHoleWidgets

# Build and test
./gradlew build test

# Run the application (without installer)
./gradlew run

Create Platform Installers:

# Windows portable ZIP
./gradlew portableZip -PinstallerType=app-image

# macOS PKG
./gradlew jpackage -PinstallerType=pkg

# Linux DEB (Debian/Ubuntu)
./gradlew jpackage -PinstallerType=deb

# Linux RPM (Fedora/RHEL)
./gradlew jpackage -PinstallerType=rpm

For detailed build instructions, see DISTRIBUTION.md.

Running the widget

After installation, launch DNSBlocker Widgets from: - Windows: Start Menu > DNSBlocker Widgets, or run directly from the portable folder - macOS: Applications folder - Linux: Applications menu (under Network or Utilities)

Context Menu (Right-click): - Hide to Tray - Minimize to system tray - Refresh All Now - Manually refresh all data - Settings - Open configuration window - Exit - Close the application

System Tray: When the widget is hidden to tray, you can: - Double-click the tray icon to restore the widget - Right-click for Show, Hide, Settings, and Exit options

Testing

App has been tested on: - Windows 10 & 11 (64-bit) - macOS (Catalina and later) - Linux Mint, Ubuntu, and Fedora

Automated builds and testing are performed via GitHub Actions on all supported platforms.

If you find any bugs or want to suggest new features, please open an issue on the GitHub tracker: FoKss-LTS/PiHoleWidgets issues

Distribution

For Developers & Distributors

This project includes comprehensive cross-platform build support:

📚 Documentation: - docs/QUICKSTART.md - Quick reference for users and developers - DISTRIBUTION.md - Detailed build and distribution guide - CHANGELOG.md - Version history and release notes - docs/project_analysis.md - Project analysis and improvement recommendations - docs/DEPENDENCY_UPDATES.md - Dependency update management guide

🔧 Build Commands:

./gradlew build test                              # Build and test
./gradlew run                                     # Run the application
./gradlew portableZip -PinstallerType=app-image   # Windows portable ZIP
./gradlew jpackage -PinstallerType=pkg            # macOS PKG
./gradlew jpackage -PinstallerType=deb            # Linux DEB
./gradlew jpackage -PinstallerType=rpm            # Linux RPM

🚀 CI/CD: - GitHub Actions automatically builds all platforms - Tagged releases create installers for Windows, macOS, and Linux - See .github/workflows/build.yml

Credits

Shoutout to :

• hans0l0 for the project TilesFX.

• afsalashyana for the helpful Covid Widget and JavaFX Tutorials.

Licence

Copyright (C) 2022 - 2025. Reda ELFARISSI aka FoKss-LTS

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Go back to : Table of Content