Here's a concise, professional technical briefing for the homepage repository, written in the style of a senior AI engineer consultant.

The Problem

This repository provides a highly customizable application dashboard with over 100 service integrations, but the codebase carries measurable structural debt that increases cognitive load for engineers making changes. A static analysis of 1,070 files found 70 issues across 5 categories, including duplicated logic, high branching density, and an empty error-catch block that silently discards failures.

What This Does

Homepage is a fully static, fast application dashboard that proxies all API requests to backend services, keeping API keys hidden. It configuration via YAML files or Docker labels, and supports over 40 languages through i18n. The source lives in src/ (1,070 files), with entry points at src/pages/index.jsx, src/pages/api/services/index.js, and src/pages/api/widgets/index.js. The widget system is the most connected module in the graph: src/components/widgets/widgets has 0 inbound imports but exports 153 modules, making it a high-instability hub (instability = 1). Changing this module carries blast-radius risk because 16 other widget containers depend on it. The widget container at src/components/widgets/widget/container.jsx is similarly popular (Ca=16, Ce=4) and is a frequent churn point. Duplicated code is rampant: 653 repeated 6-line blocks appear across 332 files, particularly in test files under src/__tests__/pages/api/docker/. An empty catch {} in src/pages/api/ping.js silently discards errors, which is a resilience risk.

How It Is Wired

Execution starts at the Next.js server entry src/pages/index.jsx, which renders the UI. API routes under src/pages/api/ handle service status, widget configuration, and proxy logic. The proxy layer in src/utils/proxy/ mediates all outbound service calls, with helpers in api-helpers.js and platform-specific handlers (e.g., synology.js). These modules have high branching density (41 branch points over 124 lines), suggesting they would benefit from decomposition via a strategy or table-dispatch pattern. Service discovery for Docker runs via container labels; the Docker integration logic lives in the API routes and widget configs, but the analysis has not mapped the exact entry-to-discovery path beyond the proxy layer. The test suite (536 files) is not invoked by any GitHub Action workflow, despite being present.

How To Use It

Setup

  • Clone: git clone https://github.com/moses-y/homepage
  • Install: pnpm install (package manager is pnpm)
  • Build: pnpm build (defined in package.json)
  • Start: pnpm start or run via Docker using Dockerfile at repo root

Configuration

  • Copy .env.example or configure via Docker labels (see docs/configs/docker.md)
  • API keys and service endpoints are set in YAML config files or injected via Docker labels
  • Environment variables are read from .env at runtime

Running it

  • Development: pnpm dev (starts Next.js in dev mode)
  • Production: pnpm start or deploy the Docker image
  • Tests: pnpm test (but this step is not in any workflow)

Real-World Use

A DevOps team deploys Homepage as an internal developer portal. They add a Plex service via Docker labels (com.gethomepage.homepage.service: plex), configure the weather widget by adding an OpenWeatherMap API key to .env, and enable the glances system widget to show container CPU/memory stats. All service API calls are proxied through the /api/ routes, so keys never surface in the browser.

Code Health & Issues

The static analysis block reports 70 findings (4 high, 66 medium, 0 low) across 5 kinds. Beyond those, the SDLC audit reveals 6 additional findings from the workflow and config review:

  • HIGH - .github/workflows: CI does not invoke the test suite (526 test files, no test: command in any of the 4 workflows). A green check that never runs assertions erodes reviewer trust.
  • MEDIUM - .devcontainer/Dockerfile: Base image mcr.microsoft.com/vscode/devcontainers/javascript-node:${VARIANT} is untagged/mutable, meaning builds pull different runtimes over time with no digest record.
  • MEDIUM - .github/workflows: No dependency vulnerability scan is gated on pull requests.
  • MEDIUM - .github/workflows/docker-publish.yml: checkout step retains the token, leaving it in .git/config for all subsequent steps.
  • MEDIUM - package.json: preinstall script runs during npm install, exposing the build to supply-chain compromise from event-stream-style malicious scripts.
  • LOW - .github/workflows/docker-publish.yml: No timeout-minutes on job steps; a wedged step could run to the six-hour platform default.

The Bottom Line

The repository functional code is sound and well-structured for a dashboard of its scale, but the CI gap (tests not executed), mutable base image, and unscanned dependencies are production-grade risks. It’s a solid choice for teams that need a proxy-rich, multi-service startpage and are willing to add the missing CI gates. Teams requiring zero-maintenance deployments should budget time for the health fixes above.