Sign inSign up

m00grin/ph-intercept

By m00grin

•Updated 2 days ago

Real-time Pi-hole, AdGuard Home & Technitium dashboard. Blocked DNS queries get shot down.

Image
Networking
Monitoring & observability
0

2.1K

m00grin/ph-intercept repository overview

⁠ph-intercept

A Pi-hole, AdGuard Home, and Technitium DNS dashboard that runs as a standalone Docker container. Streams live DNS query events from your Pi-hole v6 API and renders them as pixel-art friendlies and enemies. Blocked queries are destroyed by the ship, allowed queries fly through. Toggle blocking, set timed blocks, trigger gravity updates, and switch ships from the HUD.

Designed to be dropped in alongside an existing Pi-hole v6 setup with no extra dependencies. Two instances can run side by side in local 2-player split-screen⁠.

ph-intercept shooting down blocked DNS queries live
StarfieldNebulaOutrun
Starfield backgroundNebula backgroundOutrun background

AdGuard Home user? See the AdGuard setup guide⁠.

Technitium DNS user? See the Technitium setup guide⁠.

⁠Quick Start

1. Get your Pi-hole app password (not your web login password): from the Pi-hole admin panel, go to Settings → Web interface / API → Configure app password.

  • CLI users: Create a .env file in the same directory as your compose.yaml:

    PIHOLE_PASSWORD=your_pihole_app_password
    
  • Portainer users: Skip the .env file. Add PIHOLE_PASSWORD as an environment variable directly in the Portainer stack config.

2. Create a compose.yaml (copy the example below or grab compose.yaml⁠ from the repo) and update PIHOLE_URL to your Pi-hole's address:

services:
  ph-intercept:
    image: m00grin/ph-intercept:latest
    hostname: ph-intercept
    container_name: ph-intercept
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 128m
          cpus: "1"
          pids: 20

    environment:
      # REQUIRED: Pi-hole v6 API endpoint
      # Example: "http://192.168.1.2:80/api"
      PIHOLE_URL: "http://CHANGE.ME:PORT/api"

      # CLI users: Create a .env file in the same dir as this compose file with:
      #  PIHOLE_PASSWORD=your_pihole_app_password
      # Portainer Web users: Add the environment variable: PIHOLE_PASSWORD=your_pihole_app_password
      PIHOLE_PASSWORD: ${PIHOLE_PASSWORD}

      # Optional: where ESC navigates to (like your homelab dashboard or homepage)
      # Accepts http://, https://, protocol-relative (//), relative paths, and custom app schemes
      # Leave blank ("") to disable ESC entirely
      RETURN_URL: ""

      # Background. These set the DEFAULT; each user can also switch the background live
      # from the in-app settings menu, and their choice is remembered per-browser.
      # Style: starfield | nebula | outrun | dark
      BG_MODE: starfield

      # Sky region shown for the starfield:
      #   summer_triangle | orion | scorpius | southern_cross
      SKY_PRESET: summer_triangle

      # Optional custom background image: a URL, or /bg/your-filename.jpg (mounted volume).
      # When set, it becomes the default and enables the in-app "CUSTOM" option so it can be
      # picked any time. Leave blank to disable it (CUSTOM shows greyed out in the menu).
      BG_IMAGE: ""

      # SSL certificate verification. Set to "false" if Pi-hole uses HTTPS
      #  with a self-signed certificate. Leave as "true" for HTTP or valid HTTPS.
      PIHOLE_VERIFY_SSL: "true"

      # Optional: comma-separated regex patterns. Matching domains spawn no ships. Case-insensitive.
      # PIHOLE_IGNORE_DOMAINS: .*\.local$,.*\.internal$

      # 2-player local mode: set the URL (and password if the second Pi-hole has one)
      # to enable a second Pi-hole ship on the right half
      # PIHOLE2_URL: "http://192.168.1.3:8053/api"
      # PIHOLE2_PASSWORD: ${PIHOLE2_PASSWORD}
      # PIHOLE2_VERIFY_SSL: "true"

    volumes:
      # Portainer Web users: This will resolve to /data/compose/<stack-id>/bg/
      - ./bg:/app/static/bg
      # Persists 2-player mode state across container restarts
      - data:/app/data

    cap_drop:
      - ALL

    security_opt:
      - "no-new-privileges:true"

    read_only: true

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    ports:
      # Host port : container port. Change the left side if 4653 is taken
      - "4653:4653"

    # Optional: point DNS at your Pi-hole (if used for DNS resolution) or resolver directly (like Unbound)
    # dns:
    #   - your.dns.dockernet.ip

    # Optional: only needed if you use static IPs on a custom Docker network
    # Uncomment both networks blocks if you need this
    # networks:
    #   intercept_net:
    #     ipv4_address: this.container.dockernet.ip

# networks:
#   intercept_net:
#     external: true

volumes:
  data:

3. Start the container:

docker compose up -d

Open http://your-host:4653.


⁠AdGuard Home setup

Compose comments shared with the Pi-hole setup are trimmed here. See the Pi-hole compose above for the full notes.

⁠Quick Start

1. Have your AdGuard Home username and password ready (the credentials you use to log in to the AdGuard Home web interface).

  • CLI users: Create a .env file in the same directory as your compose.yaml:

    ADGUARD_PASSWORD=your_adguard_password
    
  • Portainer users: Skip the .env file. Add ADGUARD_PASSWORD as an environment variable directly in the Portainer stack config.

2. Create a compose.yaml (copy the example below or grab compose.yaml⁠ from the repo) and update ADGUARD_URL and ADGUARD_USERNAME to match your setup:

services:
  ph-intercept:
    image: m00grin/ph-intercept:latest
    hostname: ph-intercept
    container_name: ph-intercept
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 128m
          cpus: "1"
          pids: 20

    environment:
      PROVIDER: adguard

      # REQUIRED: AdGuard Home control API endpoint
      # Example: "http://192.168.1.2:3000/control"
      ADGUARD_URL: "http://CHANGE.ME:PORT/control"

      # REQUIRED: AdGuard Home username or email for login.
      ADGUARD_USERNAME: "CHANGE.ME"

      # CLI users: Create a .env file in the same dir as this compose file with:
      #  ADGUARD_PASSWORD=your_adguard_password
      # Portainer Web users: Add the environment variable: ADGUARD_PASSWORD=your_adguard_password
      ADGUARD_PASSWORD: ${ADGUARD_PASSWORD}

      RETURN_URL: ""

      BG_MODE: starfield

      SKY_PRESET: summer_triangle

      BG_IMAGE: ""

      # SSL certificate verification. Set to "false" if AdGuard uses HTTPS
      #  with a self-signed certificate. Leave as "true" for HTTP or valid HTTPS.
      ADGUARD_VERIFY_SSL: "true"

      # Optional: comma-separated regex patterns. Matching domains spawn no ships. Case-insensitive.
      # ADGUARD_IGNORE_DOMAINS: .*\.local$,.*\.internal$

      # 2-player local mode: set all three to enable a second AdGuard ship on the right half
      # ADGUARD2_URL: "http://192.168.1.3:3000/control"
      # ADGUARD2_USERNAME: "CHANGE.ME"
      # ADGUARD2_PASSWORD: ${ADGUARD2_PASSWORD}
      # ADGUARD2_VERIFY_SSL: "true"

    volumes:
      - ./bg:/app/static/bg
      - data:/app/data

    cap_drop:
      - ALL

    security_opt:
      - "no-new-privileges:true"

    read_only: true

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    ports:
      # Host port : container port. Change the left side if 4663 is taken
      - "4663:4653"

    # Optional: point DNS at your AdGuard Home instance
    # dns:
    #   - your.dns.dockernet.ip



volumes:
  data:

3. Start the container:

docker compose up -d

Open http://your-host:4663.


⁠Technitium DNS setup

Compose comments shared with the Pi-hole setup are trimmed here. See the Pi-hole compose above for the full notes.

⁠What you need first

ph-intercept reads two things from Technitium: the dashboard stats (built in, nothing to do) and the live query log. Technitium serves its query log through a DNS app rather than a built-in endpoint, so there is one setup step and one credential to create.

1. Install the query-log app. In the Technitium console, go to Apps -> App Store and install Query Logs (Sqlite). Despite the name there is no database to run: SQLite is embedded, so the app just writes to a file inside Technitium. This is the standard, zero-dependency choice; Technitium also offers MySQL / PostgreSQL / SQL Server variants if you already run one of those, and any of them works.

2. Create a login for ph-intercept. In the console, go to Administration -> Sessions -> Create Token and copy the token. (A username and password works too, but a token is cleaner and never expires from inactivity.)

That is the entire Technitium-side setup. If the query-log app is missing, the HUD still works (stats and the blocking toggle) but no ships spawn. If you installed the app under a custom name, set TECHNITIUM_QUERY_LOG_APP / TECHNITIUM_QUERY_LOG_CLASS to match; the defaults are Query Logs (Sqlite) and QueryLogsSqlite.App.

⁠Quick Start

1. Put the token from the step above into your environment:

  • CLI users: Create a .env file in the same directory as your compose.yaml:

    TECHNITIUM_TOKEN=your_api_token
    
  • Portainer users: Skip the .env file. Add TECHNITIUM_TOKEN as an environment variable directly in the Portainer stack config.

    (Prefer a username and password? Use TECHNITIUM_USER / TECHNITIUM_PASSWORD instead, plus TECHNITIUM_TOTP if the account has 2FA.)

2. Create a compose.yaml (copy the example below or grab compose.yaml⁠ from the repo) and set TECHNITIUM_URL to your Technitium web-console address:

services:
  ph-intercept:
    image: m00grin/ph-intercept:latest
    hostname: ph-intercept
    container_name: ph-intercept
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 128m
          cpus: "1"
          pids: 20

    environment:
      PROVIDER: technitium

      # REQUIRED: Technitium DNS web-console root (the API lives under /api).
      # Example: "http://192.168.1.2:5380"
      TECHNITIUM_URL: "http://CHANGE.ME:5380"

      # Authentication: a permanent API token (recommended) OR user + password.
      TECHNITIUM_TOKEN: ${TECHNITIUM_TOKEN}
      # TECHNITIUM_USER: "admin"
      # TECHNITIUM_PASSWORD: ${TECHNITIUM_PASSWORD}
      # TECHNITIUM_TOTP: ""   # only if the account has 2FA enabled

      # The "Query Logs (Sqlite)" DNS app must be installed in Technitium.
      # These match its default install name / class path; change only if you
      # installed the app under a different name.
      # TECHNITIUM_QUERY_LOG_APP: "Query Logs (Sqlite)"
      # TECHNITIUM_QUERY_LOG_CLASS: "QueryLogsSqlite.App"

      RETURN_URL: ""

      BG_MODE: starfield

      SKY_PRESET: summer_triangle

      BG_IMAGE: ""

      # SSL certificate verification. Set to "false" if Technitium uses HTTPS
      #  with a self-signed certificate. Leave as "true" for HTTP or valid HTTPS.
      TECHNITIUM_VERIFY_SSL: "true"

      # Optional: comma-separated regex patterns. Matching domains spawn no ships.
      # TECHNITIUM_IGNORE_DOMAINS: .*\.local$,.*\.internal$

      # 2-player local mode: set the URL and a token (or user + password) to enable
      # a second Technitium ship on the right half. The second instance also needs
      # the Query Logs (Sqlite) app installed.
      # TECHNITIUM2_URL: "http://192.168.1.3:5380"
      # TECHNITIUM2_TOKEN: ${TECHNITIUM2_TOKEN}
      # TECHNITIUM2_VERIFY_SSL: "true"

    volumes:
      - ./bg:/app/static/bg
      - data:/app/data

    cap_drop:
      - ALL

    security_opt:
      - "no-new-privileges:true"

    read_only: true

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    ports:
      # Host port : container port. Change the left side if 4673 is taken
      - "4673:4653"

volumes:
  data:

3. Start the container:

docker compose up -d

Open http://your-host:4673.


⁠Image Tags

TagWhat it is
:latestLatest stable release.
:X.Y.ZPinned release (e.g. 1.5.6).
:developBuilt automatically on every push to the develop branch. May be unstable. Good for trying out what I'm working on.

Release tags are published to both registries, so ghcr.io/m00grin/ph-intercept and docker.io/m00grin/ph-intercept (Docker Hub) are interchangeable. :develop is GHCR only.


⁠Portainer Note for BG

  • Drop image files into /data/compose/<stack-id>/bg/ on the Portainer host (where the ./bg bind mount resolves).

⁠Entities

Each DNS query spawns an entity. Tier scales with how many times that domain has queried while the entity is still on screen:

Allowed queries: friendly ships traveling across the screen. Cache-answered queries move faster than upstream-answered ones.

Friendly ships for allowed queries, including a heavy transport and a capital ship
TierConditionShapeColor
1First queryRounded shuttle · Delta wing · X-wingGreen · Blue · Lime
2Queried again while on screenHeavy transportCyan
3+Three or more queries while on screenCapital shipGold

Blocked queries: enemies the ship targets and destroys. A domain blocked again while still on screen mutates its sprite to the next tier in place.

Targeted enemies for blocked queries: crab (tier 1), heavy drone (tier 2), boss (tier 3)
TierConditionShapeColor
1First blockCrab invader · SquidRed
2Blocked twiceHeavy droneOrange
3+Three or moreBossPurple

Ship weapon color tracks tier: green for tier 1, cyan for tier 2, gold for tier 3+.


⁠The ship

The ship targets and destroys blocked entities autonomously. At five on-screen threats a support drone launches and flanks; at ten a second drone deploys. Drones are recalled when the threat count drops.

Seven ships are selectable from the HUD, shown in an 8-slot 4×2 grid: Protector (NSEA Protector, default), Falcon (Millennium Falcon), Swordfish (Swordfish II), Enterprise (NCC-1701), Serenity (Firefly), Normandy (Mass Effect), and PES (Planet Express Ship). Switching ships triggers a warp-out/warp-in transition that pushes nearby entities aside.

Ship selector

⁠The HUD

A strip across the bottom, divided into four panels:

INTERCEPT: blocking status and toggle. Click to open a menu with timed-disable options (10 sec, 30 sec, 5 min) or a full disable. A countdown shows when a timed block is active; the timer survives navigation and syncs correctly if blocking is changed remotely.

STATS: total queries, blocked, allowed, and block percentage. Updated live.

GRAVITY: gravity list size. The arrow triggers a list update and confirms when done.

SHIPS: active ship name. Click to open the ship selector.

HUD strip: intercept, stats, gravity, ship

A hamburger button at the left edge of the HUD opens the Settings panel, which includes:

  • Friendlies -- show or hide friendly (allowed) entities
  • Client -- show the requesting client (IP or hostname) as a label per entity
  • Domain -- show or hide the domain label beneath each entity
  • Pi-hole -- link to the Pi-hole admin panel

Display settings are saved to localStorage and restored on next load.


⁠The background

Four modes are available via BG_MODE:

starfield (default): Renders a real section of the night sky from an accurate star catalog (~12,200 stars to magnitude 6.8, color-coded by spectral type). Positions use equatorial coordinates; what you see is where the stars actually are. The sky region is set by SKY_PRESET.

Starfield background (Orion preset)

Star data is from the HYG Database by David Nash (astronexus.com⁠), combining Hipparcos (ESA) and the Yale Bright Star Catalogue.

Planets: Mars, Jupiter, Saturn (with ring), and the Moon are computed from real orbital elements and appear at their actual sky positions, updated hourly.

Transients: occasional satellite passes and meteors, including the ISS.

nebula: A procedurally generated nebula. Overlapping color lobes with value noise, dust lanes, and a synthetic star layer. Fully GPU-rendered, no catalog data.

outrun: A retro synthwave scene. A banded sun setting on the horizon over a scrolling neon perspective grid, with a starry sky. Pairs especially well with the CRT filter.

dark: Plain black background. No canvas rendering overhead.

BG_IMAGE: A custom image (URL or a /bg/your-file.jpg mounted into the container).

The env vars above set the default background. Each user can also switch it live from the in-app settings menu (Background), including sky presets and, when BG_IMAGE is configured, a CUSTOM option. That choice is remembered per-browser and never changes the default for anyone else. If no BG_IMAGE is set, CUSTOM simply shows greyed out. This is fully backward compatible: with no in-app choice, the env values drive everything exactly as before.


⁠Configuration

All configuration is via environment variables in compose.yaml.

Upgrading? Pulling the latest compose.yaml is recommended so you have all current environment variables on hand. Anything you don't set falls back to a sensible default, so an older compose keeps working, you just might be missing newer options.

⁠Required
VariableDescription
PIHOLE_PASSWORDPi-hole app password. CLI: set in a .env file. Portainer: add as an environment variable in the stack. Get it from Settings → Web interface / API → Configure app password.
PIHOLE_URLPi-hole v6 API base URL, e.g. http://192.168.1.x:8053/api
⁠Optional
VariableDefaultDescription
RETURN_URL""URL that ESC navigates to. Accepts http://, https://, protocol-relative (//), relative paths, and custom app schemes. Leave blank to disable ESC.
BG_MODEstarfieldDefault background: starfield · nebula · outrun · dark. Switchable live in-app.
SKY_PRESETsummer_triangleDefault sky region: summer_triangle · orion · scorpius · southern_cross. Switchable live in-app.
BG_IMAGE""Custom image URL or /bg/filename.jpg. When set, it's the default and enables the in-app CUSTOM option; blank leaves CUSTOM disabled.
PIHOLE_VERIFY_SSLtrueSet to false if Pi-hole uses HTTPS with a self-signed certificate.
PIHOLE_IGNORE_DOMAINS(unset)Comma-separated regex patterns. Domains that match spawn no ships. Case-insensitive; escape literal dots (\.local$). Example: .*\.local$,.*\.internal$
PIHOLE2_URL(unset)Second Pi-hole v6 API base URL. Setting a valid URL activates local 2-player split-screen mode. See below.
PIHOLE2_PASSWORD""App password for the second Pi-hole. Omit if it has none.
PIHOLE2_VERIFY_SSLtrueSet to false if the second Pi-hole uses HTTPS with a self-signed certificate.

⁠Local 2-Player Mode

Two DNS instances can run side by side in split-screen. Player 1's ship occupies the left half of the canvas, Player 2's ship the right. Each instance streams its own query events, stats, blocking toggle, and gravity/filter updates independently.

Add the second Pi-hole to your compose.yaml environment block:

PIHOLE2_URL: "http://192.168.1.3:8053/api"
PIHOLE2_PASSWORD: ${PIHOLE2_PASSWORD}

And add the password to your .env file:

PIHOLE2_PASSWORD=your_second_pihole_password

PIHOLE2_PASSWORD can be omitted if the second Pi-hole has no app password set. Setting a valid PIHOLE2_URL is all that is required to make the mode available; turn it on from the in-game 2-player panel. On/off state is saved to the data volume, so it survives container restarts.

AdGuard Home? The second instance mirrors your primary provider, so an AdGuard setup pairs with a second AdGuard Home via ADGUARD2_URL / ADGUARD2_USERNAME / ADGUARD2_PASSWORD. See the AdGuard 2-player setup⁠.

Technitium DNS? Pairs with a second Technitium via TECHNITIUM2_URL and TECHNITIUM2_TOKEN (or user + password). See the Technitium 2-player setup⁠.


⁠Requirements

  • Pi-hole v6 (v5 is not compatible)
  • Docker with Compose
  • Network route from the container to your Pi-hole
  • Architecture: linux/amd64 · linux/arm64 · linux/arm/v7 · linux/arm/v6 · linux/386 · linux/riscv64 · linux/ppc64le

The container listens on port 4653. The compose file includes an optional static IP block for existing Docker networks.

Curious what everyone runs it on? I'm asking in a quick poll⁠ instead of collecting any data.


⁠Troubleshooting

If something's off, check the logs first:

docker logs ph-intercept 2>&1 | grep -v '^INFO:'

On a healthy setup that prints nothing. Otherwise ph-intercept logs one line when a problem starts, and one line when it clears:

Log lineWhat to check
Pi-hole: could not reach http://... Check PIHOLE_URLThe URL and port, and that the container can reach your Pi-hole over the network.
Pi-hole: unexpected HTTP 404 reply from .../auth. Check PIHOLE_URL points at the Pi-hole v6 API (ends in /api)PIHOLE_URL must end in /api, not /admin.
Pi-hole: login rejected (password incorrect). Check PIHOLE_PASSWORDUse an app password from Settings → Web interface / API → Configure app password.
Pi-hole: login refused by rate limiting (...), retryingPi-hole throttles logins after a few quick attempts. It clears on its own within a few seconds.
PROVIDER='...' is not recognised ...PROVIDER must be pihole, adguard, or technitium (or leave it out for Pi-hole).

In 2-player mode the second Pi-hole logs the same lines as Pi-hole 2, pointing at the PIHOLE2_* variables.


⁠Privacy

ph-intercept only talks to your own Pi-hole instance(s). It never phones home, has no analytics, and collects nothing. Your display settings (ship, background, toggles) are saved in your browser's local storage and never leave it. Requests from other websites to the blocking controls are refused, so a page you visit can't toggle your DNS server through ph-intercept.


Tag summary

Content type

Image

Digest

sha256:6530d3c9d…

Size

21.5 MB

Last updated

2 days ago

docker pull m00grin/ph-intercept