The Problem

Managing a growing set of homelab services and bookmarks quickly becomes a UI and observability nightmare. Users need a single page that shows service health, system metrics, and organized links without pulling together disparate tools.

What This Does

homepage-lite is a single‑binary Go server that renders templates/index.html and serves the static assets in static/ (JS, CSS, themes). The binary (main.go) reads a config.yaml (not in the repo but referenced in the docs) to build a list of services and bookmark groups, then:

  • polls each service URL and updates status flags (UP/DOWN) every 30 s,
  • gathers CPU, memory, and disk usage via Go’s standard libraries,
  • pushes updates to the browser through Server‑Sent Events (SSE).

All UI interactions—theme switching, search, layout selection—are handled by static/app.js, while the icon set is provided by static/iconify.min.js. The Go code embeds the static files (embed.go, embed_dev.go) so the container can run without external assets.

How It Is Wired

Execution starts at main.go → func main(). The function:

  1. Calls the embed package (embed.go) to mount the static/ directory and templates/ into an in‑memory FS.
  2. Loads the YAML configuration (the code path is not exposed by the static analysis, but the README and INSTALL.md show a config.yaml).
  3. Registers HTTP handlers: / – renders templates/index.html using Go’s html/template. /static/ – serves files from the embedded FS. * /events – opens an SSE stream that periodically writes JSON payloads containing service health and system metrics.
  4. Starts http.ListenAndServe on the port defined in the config (default 8888).

The only internal modules detected are the static assets (static/app.js, static/iconify.min.js), which have no import edges, so the server side is a flat call graph with no circular dependencies. The widest blast‑radius code is the SSE handler in main.go; a failure there would stop all real‑time UI updates.

How To Use It

# Clone the upstream repository
git clone https://github.com/moses-y/homepage-lite
cd homepage-lite

# Build the binary (requires Go 1.25+)
make build            # produces ./homepage-lite

# Prepare a config file (example in README)
cp config.example.yaml config.yaml
# edit config.yaml as needed

# Run directly
./homepage-lite

# Or build and run the container
docker build -t homepage-lite .
docker run -d -p 8888:8888 -v $(pwd)/config.yaml:/app/config.yaml homepage-lite

The Makefile also defines make install to copy the binary to /usr/local/bin and set up a systemd service (homepage-lite.service). The Docker image is published to GHCR, but the repo contains a Dockerfile that builds from golang:1.25-alpine3.21.

Real‑World Use

A typical homelab deploys the binary on a Raspberry Pi. The Pi runs systemctl enable homepage-lite, mounts a persistent config.yaml on /etc/homepage-lite/, and exposes port 8888 behind a reverse proxy (Caddy/Nginx). When a new container is added to the stack, the user adds an entry to config.yaml; the running service detects the file change, triggers an SSE reload, and the dashboard updates without a restart.

Code Health & Issues

  • HIGH – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/build.yml).
  • MEDIUM – Enable Dependabot or Renovate (.github/dependabot.yml missing).
  • MEDIUM – Pin Docker base images by digest (Dockerfile).
  • MEDIUM – Add a dependency‑vulnerability scan to CI (.github/workflows).
  • MEDIUM – Run container as non‑root (Dockerfile lacks USER).
  • LOW – Set timeout-minutes on workflow jobs (.github/workflows/build.yml).

Additional observations from repository hygiene:

  • No test files present – the code paths are untested.
  • CI exists (GitHub Actions) but does not include security scanning.
  • License file is present; no secrets were found in the history.

The Bottom Line

homepage-lite delivers a lightweight, single‑binary dashboard that covers service health, system metrics, and bookmark organization with a modest resource footprint. It is production‑ready but would benefit from basic security hardening (action pinning, non‑root containers) and a test suite before being used in critical environments. Suitable for homelab operators comfortable with Go and Docker who need a simple, self‑hosted overview page.