Homepage is a self-hosted startpage application designed for users who want a fast, secure, and customizable dashboard to access their self-hosted services and web bookmarks. It solves the problem of fragmented access to tools like Radarr, Plex, qBittorrent, and other self-hosted apps by consolidating them into a single, visually appealing interface with real-time status updates. Built for developers and home server administrators, it eliminates the need to bookmark and navigate multiple URLs.
Built with Next.js and React, Homepage generates static HTML at build time for instant load performance. It supports Docker container discovery via labels, integrates with over 100 third-party services through proxied API calls, and offers full i18n support. Deployment options include Docker Compose, standalone Docker, or direct Next.js server builds, with all API requests routed through a secure proxy to protect sensitive credentials.
What You Get
- Static Site Generation - Homepage builds a fully static HTML site at build time using Next.js, ensuring instant page loads and zero server-side rendering overhead.
- Docker Service Discovery - Automatically detects and adds Docker containers to the dashboard using container labels (e.g., com.centurylinklabs.watchtower.enable), eliminating manual configuration.
- 100+ Service Integrations - Pre-built widgets for Radarr, Sonarr, Lidarr, Plex, Jellyfin, Emby, Tautulli, qBittorrent, Transmission, NZBGet, SABnzbd, and more, with real-time status and stats.
- Proxied API Requests - All external service API calls are routed through Homepage’s backend proxy, keeping your API keys and credentials hidden from the browser and preventing CORS issues.
- Multi-Language Support - Full i18n with translations in over 40 languages, managed via Crowdin and configurable per user.
- Customizable Widgets - Add weather, time, date, search, and custom Glances widgets to the top of the dashboard with configurable data sources and formatting.
- Custom Themes & CSS/JS - Override default styles with custom CSS, inject custom JavaScript, and modify layouts via YAML configuration without recompiling.
- YAML-Based Configuration - All services, widgets, and settings are defined in simple, human-readable YAML files (config.yml, services.yml, widgets.yml) for version control and easy backup.
Common Use Cases
- Managing a home media server - A user organizes Plex, Jellyfin, Radarr, and Sonarr into a single dashboard with real-time download progress and library stats, accessible from any device.
- Running a self-hosted automation hub - A tech-savvy homeowner uses Homepage to monitor Home Assistant, Node-RED, and Portainer with one-click access and status indicators.
- Deploying a team startpage for internal tools - A DevOps team creates a secure, proxied dashboard for accessing Grafana, Prometheus, GitLab, and Jenkins without exposing API keys publicly.
- Personal productivity dashboard - A remote worker combines weather, time, calendar, and bookmarks to Notion, GitHub, and email into a clean, fast-loading startpage for daily use.
Under The Hood
Architecture
- Clear separation of concerns with self-contained widget components unified through a shared API hook, ensuring consistent data flow and error handling
- Service-specific logic abstracted via proxy handlers that decouple authentication and routing, enabling reusable API clients across diverse backends
- Thin API controller layers delegate to dedicated utility modules, preserving separation between HTTP handling and business logic
- Centralized internationalization and dependency injection via modular utilities rather than global state, enhancing testability and configurability
- Modular directory structure with aliasing eliminates relative path noise and enforces clean boundaries between components, widgets, and utilities
Tech Stack
- Modern React/Next.js stack with TypeScript and SWC compilation for high-performance SSR/SSG
- pnpm with strict lockfile enforcement and optional native dependencies for system-level integrations
- Vitest with full alias resolution and coverage for comprehensive unit testing
- Tailwind CSS with plugins for utility-first styling, paired with ESLint and Prettier for consistent code quality
- Dockerized production deployment with lightweight Node.js base, health checks, and orchestration scripting
- Crowdin and MkDocs for localization and documentation, integrated with GitHub Actions for CI/CD
Code Quality
- Extensive test coverage across middleware, proxies, and widgets with robust mocking of external dependencies
- Reusable test utilities enforce uniform assertion patterns and reduce duplication
- Robust error handling with structured logging and appropriate HTTP status codes
- Strong type safety through standardized configuration shapes and predictable data expectations
- Clean, domain-focused organization with clear separation of UI, API, and test layers
- Comprehensive linting and testing integrated into the development workflow with consistent naming and structure
What Makes It Unique
- Dynamic service proxy layer with automatic session management and authentication retries for seamless integration with stateful services
- Geolocation-aware weather widget that intelligently adapts to user location with localized condition codes and graceful fallbacks
- Unified YAML-based configuration system enabling non-developers to integrate complex self-hosted services with minimal setup
- Client-side API proxy middleware that handles authentication, rate limiting, and error sanitization without external gateways
- Extensible widget architecture allowing new services to be added in under 50 lines while preserving consistency
- Host header validation middleware that enforces secure access natively, eliminating dependency on reverse proxies or cloud services