homepage

Homepage is a self-hosted application dashboard and startpage built with Next.js that aggregates all your self-hosted services into a single, visually cohesive interface. It solves the daily frustration of juggling bookmarks and separate service URLs by providing a unified, fast-loading hub with real-time status indicators and live data pulled directly from over 160 service APIs.

At its core, Homepage is fully static — the entire site is pre-rendered at build time for instant page loads with no client-side rendering overhead. All external API calls are proxied through the backend, which keeps credentials and API keys off the browser entirely. Configuration is entirely file-based using human-readable YAML, making it trivially simple to version-control, back up, and replicate across machines.

Docker integration is a first-class citizen: Homepage can automatically discover running containers via Docker labels and surface them on the dashboard without any manual configuration. For teams and power users, it also supports Kubernetes, Proxmox clusters, and custom API widgets that can pull data from any JSON endpoint. Deployment takes minutes with the official Docker image.

With over 40 language translations managed through Crowdin, full theming via custom CSS, and an extensible widget architecture that allows adding new service integrations in under 50 lines of code, Homepage strikes a rare balance between simplicity for casual self-hosters and depth for advanced homelab operators.

What You Get

• Static Site Generation - The entire dashboard is pre-built as a static site at startup via Next.js SSG, delivering instant page loads with zero server-side rendering latency on each request.
• Automatic Docker Service Discovery - Containers annotated with Homepage-specific labels are automatically detected and surfaced on the dashboard, eliminating manual service registration entirely.
• 160+ Service Widgets - Pre-built integrations for media apps (Plex, Jellyfin, Emby), download clients (qBittorrent, Transmission, SABnzbd), *arr apps (Radarr, Sonarr, Lidarr, Bazarr), and over 100 other self-hosted services with live stats.
• Server-Side API Proxy - Every widget request is routed through Homepage’s Next.js API layer, so API keys and credentials are never exposed to the browser, preventing both CORS issues and credential leakage.
• Kubernetes and Proxmox Integration - Native support for Kubernetes cluster discovery and Proxmox node/VM widgets, extending the dashboard beyond home setups to production-adjacent homelabs.
• Built-in MCP Server - An optional Model Context Protocol server endpoint allows AI assistants to query and interact with the dashboard programmatically via a bearer token.
• YAML-Based Configuration with Environment Variable Substitution - All configuration lives in plain YAML files with support for {{HOMEPAGE_VAR_*}} and {{HOMEPAGE_FILE_*}} substitutions for secrets management without hardcoding credentials.
• Custom Themes, CSS, and JavaScript Injection - Apply full custom stylesheets and inject arbitrary JavaScript from dedicated config files, enabling unlimited visual customization without touching source code.

Common Use Cases

• Centralizing a home media server - A user running Plex, Radarr, Sonarr, and qBittorrent deploys Homepage to see library sizes, active downloads, wanted items, and missing episodes at a glance from a single tab.
• Running a homelab operations dashboard - A homelab operator uses Homepage to monitor Proxmox VMs, Grafana alerts, Portainer containers, and Uptime Kuma checks from one place, with real-time status indicators.
• Deploying a secure team startpage for internal tools - A small DevOps team exposes Grafana, GitLab, Jenkins, and Vault behind a reverse-proxied Homepage instance, keeping all API keys server-side and access gated by OIDC login.
• Building a personal productivity hub - A remote worker combines weather, system resource widgets, a search bar, web bookmarks, and calendar events into a fast-loading browser homepage that replaces the default new tab page.
• Managing a multi-tenant self-hosted stack - A power user leverages Homepage’s tab system and Docker label discovery to organize dozens of containers into logical groups — media, networking, security, dev tools — without writing service configs manually.

Under The Hood

Architecture Homepage follows a clean separation between static rendering and dynamic data retrieval. The Next.js static generation layer compiles the page shell at build time, while a set of server-side API routes act as a dedicated proxy tier that fetches live data from external services on demand. Widget components on the client side consume these proxied endpoints via SWR, keeping the client thin and stateless. The middleware layer enforces Host header validation and optional OIDC authentication before any request reaches the API routes, providing a security perimeter that does not depend on external tools. A modular widget registry maps service types to their proxy handlers and endpoint configurations, making it straightforward to add integrations without modifying the routing layer.

Tech Stack The project is built on Next.js 16 with React 19 and compiled using SWC for fast builds. Data fetching on the client uses SWR for request deduplication and background refresh. Server-side integrations include dockerode for Docker API access, @kubernetes/client-node for Kubernetes cluster queries, and systeminformation for local resource metrics. Styling is handled by Tailwind CSS v4 with PostCSS. Authentication is powered by next-auth v4 with OIDC support. Internationalization uses i18next and next-i18next with over 40 Crowdin-managed locales. The production Docker image is built on Node 22 Alpine with a multi-stage Dockerfile producing a minimal standalone Next.js output.

Code Quality The codebase has comprehensive test coverage across middleware, proxy handlers, individual widget configurations, and React components, with over 500 test files using Vitest and Testing Library. Shared test utilities enforce consistent assertion patterns across widget tests. Error handling follows explicit patterns throughout the proxy layer — failed HTTP calls are logged with structured winston output and surfaced to the UI with sanitized error payloads. ESLint and Prettier are enforced with import ordering rules, and GitHub Actions runs CI on every push. Type safety is managed via jsconfig.json path aliases and consistent data shape conventions rather than full TypeScript, with TypeScript present as a dev dependency for tooling support.

What Makes It Unique Homepage’s standout feature is its server-side proxy architecture that handles authentication, session management, and credential isolation without requiring any external API gateway — every widget call is a thin wrapper around a proxied backend fetch that the browser never touches. The automatic Docker label discovery mechanism means that in a typical Compose-based homelab, adding a service to the dashboard is as simple as adding two container labels. The recently added MCP server endpoint is a forward-looking integration that makes Homepage queryable by AI assistants. The extensible widget system maintains a consistent component contract across 160+ integrations, enabling the community to contribute new service widgets with minimal boilerplate.

Self-Hosting

Homepage is released under the GNU General Public License v3.0 (GPL-3.0). This is a strong copyleft license that grants you the right to use, modify, and redistribute the software freely for personal and commercial purposes. The key implication of GPL-3.0 for self-hosters is that if you distribute a modified version of Homepage — for instance, packaging it as part of a commercial appliance or service — you must make your source changes available under the same license. Running Homepage privately on your own infrastructure, even in a commercial setting, does not trigger this distribution requirement. There is no open-core or proprietary add-on tier; all features are available under the same license.

Running Homepage yourself is operationally straightforward. The official Docker image is the recommended deployment path and requires only a Docker host, a writable config directory, and optional access to the Docker socket for container discovery. You are responsible for placing it behind a reverse proxy (such as Nginx, Traefik, or Caddy) that enforces TLS and, if exposed to untrusted networks, authentication via the built-in OIDC/password flow or an upstream auth provider. Updates require pulling the new image tag and restarting the container — there is no database to migrate and no persistent state beyond your YAML config files. Backups are as simple as copying the config directory.

Homepage has no managed cloud offering or paid tier. Everything you need is in the open-source release, which means you gain complete control over your data and no subscription dependency, but you also take on full responsibility for uptime, security patching, and upgrades. The trade-off versus a hypothetical hosted service is that there is no SLA, no vendor support channel beyond the GitHub Discussions community, and no automatic high-availability setup — though the stateless architecture makes it trivial to run multiple replicas behind a load balancer if uptime matters.