Introduction: The Need for an On-Demand Tracker

Between multiple iMacs, a Windows laptop, family iPads, a networked printer, smart TVs, and a revolving door of smartphones—including the two iPhones Lisa carries (one purely for her work)—our home local area network (LAN) handles a heavy volume of active clients. As an administrator, I want to be able to monitor and manage admin tasks on these devices remotely within the LAN without having to physically sit in front of them or guess their current network footprints.

When designing a dashboard to track them, standard tracking methods fell incredibly short:

• The nmap Problem: Relying on network sweeps like nmap is notoriously slow, lagging behind system changes and dragging down performance.
• The Interval Trap: Standard background polling setups run on rigid intervals (like every 5 minutes). This is deeply flawed. If I just walk through the front door and the system performed its check a minute prior, none of my freshly connected devices will show an active lease entry. I have to wait around for a stale timer to expire just to see my own network state.

I wanted a solution that was entirely on-demand. It shouldn't waste system resources polling in the background when nobody is watching; instead, it should pull live telemetry only when I am actively interested in looking at the dashboard.

Knowing that I could natively access my router's internal lease mappings through an authenticated secure shell (SSH) session—and having recently learned how to harness light, event-driven webhooks—I realized I had all the raw ingredients needed to build a real-time bridge. By combining Docker, an Asuswrt-Merlin gateway, and dynamic API endpoints, I built a reactive sync engine. Everything works out great, and here is exactly how to set it up.

Executive Summary

Modern self-hosted dashboards like Homepage are fantastic for consolidating homelab links, but they are traditionally static or pull data via rigid, pre-built integrations. This article outlines the architecture and troubleshooting lifecycle required to build a highly responsive, custom network tracker.

By leveraging an explicit architecture utilizing a custom Alpine Linux Docker container, security-scoped SSH bridges, and an on-demand Webhook trigger system, we successfully mapped real-time client lease connections from an Asus router running Asuswrt-Merlin firmware directly onto a clean frontend UI wrapper without running the stack under root privileges.

1. System Architecture & Flow

The goal of this project was to avoid heavy background polling intervals and instead create a reactive setup: whenever Homepage is loaded or refreshed in a browser, it fires a query that triggers a network scrape, rewrites the layout configuration, and updates the UI seamlessly.

[Browser: Homepage UI] 
       │
       ▼ (HTTP GET Widget Hook)
[Docker: network-webhook Container (Non-Root)] 
       │
       ▼ (SSH Auth over Port 8022 using id_ed25519)
[Asus Router Local Gateway] ──> (Scrapes Client Leases)
       │
       ▼ (Streams buffer edits via "tee")
[services.yaml File Updates] 
       │
       ▼ (Returns API Payload String)
[Clean UI Component Renders on Screen]

2. Component Design & Configurations

To achieve this safely and reliably, three major components had to be engineered to interact perfectly inside an isolated Docker network bridge.

A. The Secure Custom Dockerfile

To avoid running containers as root while still gaining access to network tooling (ssh) and standard scripting interpreters (bash), we baked the dependencies directly into the build layer using a multi-user custom image.

FROM almir/webhook:latest

# Temporarily switch to root to install the required utilities
USER root

# Install bash shell and secure shell client dependencies
RUN apk add --no-cache bash openssh-client

# Drop privileges back to the safe, default webhook user
USER webhook

B. Docker Compose Stack (docker-compose.yml)

The composition layer maps host file systems natively into the container space, ensuring your configurations, templates, and host SSH identity keys are cleanly mounted.

services:
  webhook:
    build: .  # Points to the Dockerfile in the execution directory
    container_name: network-webhook
    ports:
      - 9000:9000
    volumes:
      - /home/username/homepage/config:/config
      - ./hooks.json:/etc/webhook/hooks.json
      - ~/.ssh:/home/webhook/.ssh:ro # Mapped directly to non-root home directory read-only
    command: -verbose -hooks=/etc/webhook/hooks.json -hotreload
    restart: unless-stopped

C. Webhook Router Orchestration (hooks.json)

The webhook engine listens on port 9000 for an explicit execution pattern. It triggers our script background routine and requires explicit commands to return standard-output streams back over HTTP.

[
  {
    "id": "refresh-network",
    "execute-command": "/config/update_homepage.sh",
    "command-working-directory": "/tmp",
    "include-command-output-in-response": true,
    "response-headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

3. Engineering Obstacles & Critical Lessons Learned

Building bespoke custom systems between infrastructure layers often brings subtle environment constraints to light. Over the course of development, several critical architectural anomalies had to be solved:

Lesson 1: The Linux Shebang & Carriage Return Trap

When writing scripts on a desktop client, text editors occasionally inject Windows-styled line endings (CRLF). When mounted inside an Alpine Linux container, the interpreter reads the shebang line as #!/bin/bash\r. Because it looks for a literal file path named bash\r (which does not exist), Linux throws a highly misleading error:

fork/exec /config/update_homepage.sh: no such file or directory

The Fix: Stripping invisible carriage returns via regex parsing or shifting text editors to strict LF mode instantly clears kernel execution lines.

sed -i '' 's/\r$//' update_homepage.sh

Lesson 2: Asuswrt-Merlin Volatile Key Reset & Dropbear Authentication Failures

The lightweight SSH daemon on Asuswrt-Merlin (Dropbear) behaves uniquely. While the /jffs flash partition is persistent, Dropbear strictly reads user authentication keys from a temporary, RAM-backed runtime directory (/root/.ssh/authorized_keys). On a standard reboot, this folder is completely wiped and regenerated with an empty file by the firmware, breaking automated public-key authentication and reverting back to a password prompt.

Furthermore, Dropbear will ignore public keys entirely if directory ownership permissions are too open, or if an empty placeholder file blocks directory assignments during initialization.

The Fix: We anchor our key permanently in flash memory under /jffs/.ssh/authorized_keys. Then, we leverage Merlin's native user-scripting architecture to forcefully remove the empty phantom profile on boot and symlink it straight to our flash memory. By creating a script at /jffs/scripts/services-start, we automate the link injection sequence perfectly on system startup:

#!/bin/sh

# 1. Clear out the empty system-generated placeholder file
rm -f /root/.ssh/authorized_keys

# 2. Ensure the profile directories exist
mkdir -p /root/.ssh
chmod 700 /root/.ssh

# 3. Drop a clean symlink straight to our persistent JFFS keys
ln -sf /jffs/.ssh/authorized_keys /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys

Making the user script executable completes the workaround:

chmod +x /jffs/scripts/services-start

Architecture Note: Because this implementation creates a live symbolic link, standard helper scripts like ssh-copy-id executed from your workstation remain fully operational. The router intercepts the append commands and updates the persistent JFFS flash storage dynamically.

Lesson 3: Docker Key Identity Alignment

An SSH client automatically looks for standard identities (like id_ed25519) within its active user profile space. Because our container executes under a localized, unprivileged webhook user (UID 1000), it lacks access to the host machine's home tree. By mounting the host's ~/.ssh path directly to /home/webhook/.ssh:ro, OpenSSH automatically navigates through its fallback hierarchy, scans past missing RSA models, and authenticates using the native ED25519 signature seamlessly.

Lesson 4: Folder Permission Isolation & The Pipeline Output Strategy

When updating dashboard files from inside a container, using standard redirection operators (like >) instructs Linux to truncate the old file and create a brand new file object on disk. This action requires elevated write permissions on the parent folder.

To preserve strict directory security guidelines, the script uses a pipeline layout with tee. This writes modifications directly into the globally open file buffer (666) without altering the parent directory parameters (755).

Lesson 5: Strict UI Framework Constraints (React Error #31)

Homepage utilizes Next.js and React on its frontend framework. React strictly forbids rendering nested, raw JSON objects directly into standard string components. When our endpoint passed a structured dictionary like {"status": "Live Sync Active"}, or returned chatty text lines during debugging phases, the interface completely crashed with a minified runtime error #31 or an "Invalid data" error payload.

The Fix: We stripped out all conversational diagnostics from the production script, leaving it to respond with an isolated, flat text string enclosed in double quotes ("Live Sync Active"). This registers cleanly as a string literal across both the JSON validation engine and the React render tree.

4. The Final Blueprint: Complete Script & Dashboard Component

Below is the complete, streamlined production automation script. Save this file to your mapped volume location at /home/username/homepage/config/update_homepage.sh:

#!/bin/bash

# Configuration Paths
TEMPLATE="/config/services.yaml.template"
TARGET="/config/services.yaml"
TEMP_DEVICES="/tmp/router_devices.txt"

# 1. Fetch live leases from Asus Merlin via SSH and format directly into Homepage YAML schema
# OpenSSH automatically scans ~/.ssh/ inside the container and picks up the mounted id_ed25519 key
ssh -o StrictHostKeyChecking=no -o PasswordAuthentication=no -p 8022 This email address is being protected from spambots. You need JavaScript enabled to view it..1.1 "cat /var/lib/misc/dnsmasq.leases" | awk '
{
    hostname = $4
    ip = $3
    mac = $2

    # Provide fallback mapping for devices running without a broadcast hostname
    if (hostname == "*") { hostname = "Unknown-" mac }

    printf "    - %s:\n", hostname
    printf "        icon: mdi-network-outline\n"
    printf "        description: \"IP: %s\"\n", ip
    printf "        ping: %s\n", ip
}' > "$TEMP_DEVICES"

# 2. Insert the active array directly into the placeholder marker within your template.
# Using 'tee' streams content into the file buffer, keeping your parent folder locked down.
sed -e "/# ROUTER_DEVICES_PLACEHOLDER/r $TEMP_DEVICES" "$TEMPLATE" | tee "$TARGET" > /dev/null

# 3. Housekeeping
rm -f "$TEMP_DEVICES"

# 4. Clean API Output (Keeps Webhook parsing engines completely silent and happy)
echo '"Live Sync Active"'

With the orchestration components complete, the final frontend layout is dropped into your homepage dashboard configuration tree:

- Home Network Status:
    - Network Status:
        icon: mdi-router-wireless
        widget:
          type: customapi
          url: http://host.docker.internal:9000/hooks/refresh-network
          method: GET
          mappings:
            - container: text
              label: Network Status

- Home Network Devices:
# ROUTER_DEVICES_PLACEHOLDER