Homer

Homer is a static, single‑page application that acts as an on‑premises dashboard for any self‑hosted stack. At its core, it renders a collection of “cards” that link to services, documentation, or external URLs. The entire UI is generated from a single config.yml file located in the assets/ directory, making it trivial to version‑control or share across environments. Because all assets are static, the application can be served by any HTTP server (NGINX, Apache, Caddy) or via a container orchestrator such as Docker Swarm or Kubernetes without requiring a runtime environment beyond the web server.

Architecture & Technical Stack

• Frontend: Pure HTML/CSS/JavaScript, built with Vue.js 3 (via the Vite build tool). The source code is transpiled and bundled into a single index.html that references minified JS/CSS assets. No server‑side rendering is performed; all logic runs in the browser.
• Configuration: YAML, parsed client‑side by a lightweight JavaScript library (js-yaml). The schema supports nested pages, groups, custom icons (SVG or FontAwesome), color themes, and advanced features such as fuzzy search and keyboard shortcuts.
• Deployment: The Docker image (b4bz/homer) is a minimal Alpine‑based container that simply serves the static files via an embedded HTTP server (Caddy). It exposes a single port (default 8080) and mounts the assets/ directory for configuration. Kubernetes manifests are provided in the repo, enabling Helm‑style deployments.
• No Database: All state is stored in the YAML file; there is no persistence layer, which simplifies scaling and eliminates operational overhead.

Core Capabilities & Extensibility

• Smart Cards: Each card can specify a custom target (_target), icon, color, and even an embedded script to fetch dynamic data (e.g., uptime from a REST endpoint). The card component is exposed as a reusable Vue component, so developers can fork the repo and extend it with new card types.
• Theming: Themes are defined in a separate YAML file (themes.yml) and can be swapped at runtime via a query parameter or a UI selector. CSS variables drive the visual appearance, allowing fine‑grained control over colors, fonts, and spacing.
• Keyboard & Search: Built‑in fuzzy search (leveraging Fuse.js) and global keyboard shortcuts (/, Esc, Enter) provide a desktop‑like experience. These features are exposed as public functions, enabling integration into larger SPA frameworks if desired.
• Plugin Hooks: While Homer itself does not expose a formal plugin API, the open‑source nature and modular Vue components make it straightforward to fork or contribute new modules. The repo’s docs/development.md outlines the build process and component architecture, facilitating custom extensions.

Deployment & Infrastructure

• Containerization: The official Docker image is intentionally slim, using Alpine and Caddy. It can be run with a simple bind‑mount of the configuration directory, preserving file ownership (UID/GID 1000 by default) and ensuring zero‑downtime reloads when the config changes.
• Scalability: Because Homer is purely static, horizontal scaling is trivial—any number of replicas behind a load balancer will serve identical content. The lack of session state means no sticky sessions are required.
• CI/CD Friendly: The static build can be integrated into CI pipelines; the YAML configuration can be templated with tools like Helm or Kustomize, allowing environment‑specific dashboards without manual editing.
• Security: Serving static files reduces the attack surface. The container exposes only HTTP, and any authentication must be handled by the front‑end proxy (e.g., BasicAuth in NGINX or OAuth via a reverse proxy).

Developer Experience & Community

• Documentation: The repo contains comprehensive docs (docs/) covering configuration, theming, smart cards, and development. The configuration.md file details every field, making it straightforward to author dashboards programmatically.
• Community: With over 30k GitHub stars and inclusion in the Awesome Self‑Hosted list, Homer has an active contributor base. Issues are usually triaged quickly, and pull requests for new card types or themes are accepted with minimal friction.
• Licensing: Apache 2.0 permissive license removes concerns about commercial use or redistribution, which is a key advantage for enterprise deployments.

Use Cases

1. Internal Ops Dashboards – A DevOps team can expose a single landing page that links to Grafana, Prometheus, Kubernetes dashboards, and CI pipelines, all grouped by environment.
2. Developer Onboarding – New contributors can be pointed to a self‑hosted Homer instance that aggregates documentation, issue trackers, and code repositories.
3. IoT Gateways – Embedded devices can host a lightweight Homer page to expose status metrics and control panels without installing heavyweight web frameworks.
4. Service Catalogs – SaaS providers can offer a customizable, self‑hosted portal for customers to access their services and support resources.

Advantages Over Alternatives