Project ten, an app dashboard (Heimdall-style)

Prerequisites and companion example

You need Node.js 22, pnpm, and the repository dependencies. The example lives in examples/app-dashboard and uses local KV. Copy the local secret, then start the Worker:

cp examples/app-dashboard/.dev.vars.example examples/app-dashboard/.dev.vars
pnpm wrangler dev --config examples/app-dashboard/wrangler.jsonc

In another terminal, run node --test examples/app-dashboard/test/index.test.mjs; six tests should pass. Add two applications with the README curl commands and expect status 201; opening http://127.0.0.1:8787/ shows the tile grid; /api/health returns up or down per application. A management request without an Authorization header must return 401; a non-http(s) url must return 400 invalid_url.

Clarify first: Heimdall cannot run on Cloudflare

The Heimdall that user communities refer to is linuxserver/Heimdall (9000+ stars). It is a PHP/Laravel application distributed for Docker/VPS only, and it cannot run on Cloudflare Workers or Pages; the Cloudflare ecosystem currently has no mature Heimdall replacement either. If you want a no-code option, build gethomepage/homepage (32000+ stars) into a fully static site and host it on Cloudflare Pages. This project demonstrates the third path: write a minimal, fully controllable dashboard yourself with Workers + KV, in exchange for full control over authentication, health-check logic, and boundaries.

Design: Worker-rendered tiles plus a KV manifest

A dashboard does not need a framework. One Worker reads the apps key from KV on GET / (a JSON array with id, name, description, url, healthUrl per entry) and renders the tile grid on the server: each tile shows the name, the description, and the first letter of the name as the icon, and the whole tile links to the application. Every user-controlled field is HTML-escaped before rendering, and url is restricted to http/https on write, so pseudo-protocols such as javascript: never reach an href.

const apps = await env.DASHBOARD_KV.get('apps', 'json');
const tiles = (apps ?? []).map((app) => `
  <a class='tile' href='${escapeHtml(app.url)}' rel='noopener noreferrer'>
    <span class="icon">${escapeHtml(app.name[0].toUpperCase())}</span>
    <span class="name">${escapeHtml(app.name)}</span>
  </a>`);

KV fits this manifest: read-heavy, small values, and second-level eventual consistency is acceptable. Cap the application count (50 in the example) so the list cannot grow without bound and slow rendering.

Health checks: parallel subrequests with a 60 second cache

GET /api/health issues a Worker subrequest against each application's healthUrl. Promise.allSettled runs them in parallel so a single failure cannot drag down the whole check; AbortSignal.timeout(3000) bounds every probe at three seconds, and timeouts and connection refusals both map to down. Results are written to KV keyed by health URL with expirationTtl: 60; cache hits return immediately without any subrequest:

const settled = await Promise.allSettled(
  misses.map((app) => fetchImpl(app.healthUrl, { signal: AbortSignal.timeout(3000) })),
);
// Cached apps are skipped entirely; probe results for misses are written back to KV with a 60 second TTL

Management API and input validation

POST /api/apps and DELETE /api/apps/<id> require Authorization: Bearer <ADMIN_KEY>; both sides are SHA-256 hashed and compared byte-by-byte so timing differences do not leak the secret. New applications are validated: name is 1 to 60 characters, description is at most 160 characters, url must be a valid http/https URL, and healthUrl is optional and falls back to url. A body over 4KB returns 413, a non-JSON body returns 415, and a full manifest returns 409 app_limit_reached.

Verification and troubleshooting

Remote boundary and rollback

Creating a remote KV namespace, writing a production secret, or deploying the Worker changes Cloudflare state; this tutorial does not run those actions. On rollback, remember that reverting code does not remove the application manifest or the health cache already written to KV. The health: keys expire on their own after the 60 second TTL, but the apps manifest must be removed explicitly through the management API or wrangler kv key delete. If a new health-check revision misjudges targets and triggers alert noise, roll back to the stable code first, then audit any stale cache keys left in KV.

Next: choose the right storage service by data shape.

Primary sources

• Workers KV
• Cloudflare Workers