leufrasiojunior/yapd repository overview

⁠YAPD

YAPD - Yet Another Pi-hole Dashboard is a self-hosted dashboard for managing multiple Pi-hole v6+ instances from one place.

It provides dashboards, instance health, query visibility, configuration management, synchronization, drift detection, audit history, notifications, and Pi-hole administration workflows.

YAPD is designed primarily for trusted private networks such as LAN or VPN environments.

⁠Links

• Docker image: leufrasiojunior/yapd:latest
• GitHub repository: https://github.com/leufrasiojunior/yadp⁠
• Production compose.yml: https://github.com/leufrasiojunior/yadp/blob/main/compose.yml⁠
• Direct compose.yml download: https://raw.githubusercontent.com/leufrasiojunior/yadp/main/compose.yml⁠

⁠What YAPD Provides

• Centralized view for multiple Pi-hole v6+ instances
• Instance health and operational status
• Query visibility and historical analysis
• Configuration management and synchronization workflows
• Drift detection between Pi-hole instances
• Audit history for administrative actions
• Application notifications
• Pi-hole administration workflows from a single interface

⁠Runtime Model

The Docker image runs the web UI and API in a single application container.

• Web UI is served by the internal application proxy on port 80
• HTTPS is available on port 443 with the container certificate
• The NestJS API runs internally on port 3001
• PostgreSQL is required as a separate database service
• Prisma migrations are applied automatically when the application container starts

⁠Production Deployment

Use the production compose.yml from the GitHub repository as the deployment reference.

The production compose.yml uses postgres:16-alpine for the database and leufrasiojunior/yapd:latest for the application container. It creates a private Docker network between YAPD and PostgreSQL and stores database data in a persistent Docker volume.

By default, the production compose.yml publishes:

• HTTP on host port 48080
• HTTPS on host port 48443

Before starting the stack, edit the required values in compose.yml:

• PostgreSQL password
• SESSION_SECRET
• APP_ENCRYPTION_KEY
• WEB_ORIGIN
• WEB_PUSH_VAPID_SUBJECT

Keep APP_ENCRYPTION_KEY stable after setup. Changing it later can make encrypted Pi-hole credentials and stored push keys unreadable.

⁠Reverse Proxy

For most public or remote deployments, place YAPD behind an external reverse proxy such as Nginx, Caddy, Traefik, or Nginx Proxy Manager.

Recommended topology:

Browser to public HTTPS domain, then external reverse proxy, then HTTP to the YAPD host on port 48080.

Set WEB_ORIGIN to the exact public browser URL, for example https://yapd.example.com⁠. Keep COOKIE_SECURE=true when users access YAPD through HTTPS.

⁠Push Notifications

Browser push notifications require a trusted secure browser context.

Use HTTPS with a certificate signed by a trusted certificate authority, such as Let's Encrypt. Direct HTTP access through an IP address or a self-signed or untrusted certificate keeps browser push notifications disabled.

The backend connection between your reverse proxy and the YAPD container can remain HTTP on your private network. What matters for browser push notifications is the public URL used by the browser.

⁠First Access

On first access, YAPD redirects to the setup wizard where you configure the initial Pi-hole instances, baseline, login mode, and preferences.

There is no static default admin account intended for production use. Complete the setup flow after the first startup.

⁠Swagger

Swagger/OpenAPI documentation can be enabled with SWAGGER_ENABLED=true.

When enabled, the API docs are available at /api/docs through the public YAPD URL.

⁠Project Status

YAPD is under active development. It is intended for home labs, small networks, and trusted LAN/VPN environments running Pi-hole v6+.