Enhance Pi-hole API proxy, caching, and mobile UI features

[surajverma]

This pull request introduces several improvements to Pi-Dash, focusing on enhanced configuration flexibility, improved Docker and CI/CD support, expanded documentation, and a new custom CSS file for better dashboard appearance and responsiveness. The most significant changes are grouped below.

Configuration and Documentation Enhancements:

• config-example.json, README.md: Expanded configuration options for Pi-hole instances, including new settings like queries_refresh_interval, cache_ttl, show_network_summary, show_trends, and verify_ssl. The example now uses environment variable references for sensitive values, with detailed explanations and usage instructions added to the documentation. [1] [2]
• README.md: The documentation has been extensively rewritten for clarity, with improved feature descriptions, configuration tables, installation instructions (including Docker Compose, Docker Run, and native), and a new section on health checks and development/testing. [1] [2]

Docker and CI/CD Improvements:

• Dockerfile: The build now creates a non-root user for better security, uses gunicorn for production serving, and adds a health check endpoint.
• .dockerignore: Excludes test directories, test results, and .git from Docker builds to reduce image size and improve build performance.
• .github/workflows/test.yml: Adds a new GitHub Actions workflow to run backend and frontend tests, perform syntax checks, verify builds, and upload test artifacts.
• README.md: Adds a badge for the new test workflow.

Frontend Styling:

• css/dashboard.css: Introduces a new custom CSS file, providing improved layout, responsive design, status indicators, and better mobile support for the dashboard.

These changes collectively make Pi-Dash more robust, secure, configurable, and user-friendly, with clearer documentation and improved development workflows.

[Copilot]

🟡 Changes recommended

The proxy endpoints currently 500 on non-integer length query params and the browser test fixture server binds to 0.0.0.0, unnecessarily exposing it beyond localhost.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR modernizes Pi-Dash’s backend proxy and frontend dashboard to support richer Pi-hole status reporting, safer/easier configuration, and improved responsiveness—backed by a new automated regression test suite and updated deployment guidance.

Changes:

• Refactors the Flask proxy to add per-instance health/blocking metadata, a network summary, and a shared backend cache with configurable TTL.
• Reworks the dashboard UI for mobile/desktop behavior (expandable cards, query panel), and introduces a shared “core” module to support Node/jsdom tests.
• Adds CI workflow coverage (Python + Node + Playwright rendered checks), updates Docker runtime (non-root + gunicorn), and expands documentation/config examples.

File summaries

File	Description
tests/test_proxy.py	Adds Python regression tests for config compatibility, caching, summary behavior, and routes.
tests/lifecycle.test.cjs	Adds jsdom lifecycle tests for abort/recovery behavior and timer correctness.
tests/dashboard.test.cjs	Adds jsdom behavior tests for query grouping/tracking, mobile UI, and XSS safety for names.
tests/browser/server.cjs	Adds a local fixture server to render production assets with synthetic API responses.
tests/browser/run.cjs	Automates Playwright runs for rendered layout + offline/online lifecycle checks and screenshots.
tests/browser/mock.js	Injects synthetic fixture data and hooks fetch/timers for rendered regression checks.
tests/browser/index.html	Adds a small harness page to drive fixture iframes and rendered checks.
tests/browser/checks.js	Implements browser-only geometry/layout and lifecycle assertions across viewports/scenarios.
tailwind.config.js	Enables Tailwind darkMode: 'class' for explicit theme class behavior.
sw.js	Updates PWA caching strategy and app-shell assets; avoids caching API responses.
src/tailwind.css	Removes inline custom CSS (moved to dedicated dashboard stylesheet).
requirements.txt	Simplifies Python deps and adds gunicorn for production serving.
README.md	Major rewrite: new configuration options, install guidance, and development/testing instructions.
proxy.py	Refactors proxy to add caching, health endpoint, richer data model, and config helpers.
package.json	Adds jsdom/playwright and introduces test/dev scripts alongside Tailwind build.
js/dashboard-core.js	New shared pure helpers for formatting, health/status, and query tracking/grouping.
js/app.js	Rewrites dashboard runtime: polling lifecycle controls, mobile card toggles, query feed panel, trends.
index.html	Updates markup for network summary + query panel + loads new dashboard CSS and core JS.
Dockerfile	Improves container security (non-root), adds healthcheck, switches to gunicorn.
css/style.css	Updates generated Tailwind output to match new markup/classes.
css/dashboard.css	Adds custom responsive styling for desktop/mobile cards, query panel, and status indicators.
config-example.json	Expands example config with new options and env-var password reference.
.gitignore	Adds ignores for Python cache and rendered test artifacts.
.github/workflows/test.yml	Adds CI workflow for Python tests, Node tests, Tailwind build, and Playwright rendered checks.
.dockerignore	Excludes tests, artifacts, and .git from Docker build context.

Review details

Files not reviewed (1)

• css/style.css: Generated file

Suppressed comments (1)

proxy.py:419

• /queries parses length with int(...) directly; a non-integer query param will raise ValueError and return a 500. Use the existing _int helper so invalid input falls back to the default and remains clamped.

        length = max(1, min(int(request.args.get('length', 50)), 200))
        return jsonify(fetch_queries(length))

• Files reviewed: 21/25 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.