Homepage

Homepage by gethomepage is a self‑hosted personal dashboard that turns static assets into a highly interactive, fully proxied interface for over 100 services. At its core the application is a static site generator written in Go, which compiles user‑defined YAML manifests into a single-page application that runs entirely in the browser. The static build is served via any web server or CDN, while a minimal Go runtime exposes a lightweight API layer for authentication, proxying external service calls, and Docker integration. This separation of concerns gives developers fine‑grained control over caching, edge deployment, and security policies while keeping the front‑end lean.

Architecture

• Language & Runtime: Go 1.22+ powers both the build tool and optional runtime API, leveraging Go’s static binaries for cross‑platform distribution (AMD64, ARM64).
• Template Engine: The front‑end is built with React (Vite) and rendered into a single index.html. The build process injects configuration data via JSON blobs, enabling the UI to be completely static after deployment.
• Data Store: No external database is required; all configuration lives in YAML files or Docker labels. For advanced use cases, a lightweight key‑value store can be injected behind the API to persist user preferences.
• Proxy Layer: The Go server exposes a /api/proxy endpoint that forwards authenticated requests to target services, stripping API keys from client requests and preventing CORS or credential leakage.
• Docker Integration: By reading Docker labels (homepage.group, homepage.widget), the runtime can auto‑discover containers, expose their status, and generate corresponding widgets without manual YAML edits.

Core Capabilities

• Service Widgets: Pre‑built integrations for 100+ services (Radarr, Sonarr, Plex, Emby, etc.) expose health, statistics, and control actions via the proxy API.
• Custom Widgets: Developers can implement any REST endpoint and expose it as a widget using the widget configuration.
• Search & Bookmarks: Built‑in search engine and bookmark system support custom URLs, tags, and categories.
• Internationalization: i18n is handled through JSON translation files; developers can add new locales by extending the locales/ directory.
• API Hooks: Webhooks and callbacks can be configured to trigger external actions (e.g., start/stop containers) via the /api/hook endpoint.

Deployment & Infrastructure

• Self‑Hosting: The application can run as a single binary or via Docker Compose. It requires only a Go runtime (or container) and a static web server for the generated assets.
• Containerization: Official images are available on Docker Hub (gethomepage/homepage) with multi‑arch support. The container can be configured through environment variables or mounted configuration volumes.
• Scalability: Since the front‑end is static, CDN edge caching can be leveraged for global reach. The API layer scales horizontally behind a load balancer; each instance shares the same configuration files or a shared NFS volume.
• Security: All API keys are stored server‑side; the proxy enforces rate limiting and can integrate with OAuth or JWT for user authentication. TLS termination is typically handled by the reverse proxy (NGINX, Traefik).

Integration & Extensibility

• Plugin System: Developers can write Go plugins that register new widget types or modify the proxy behavior at runtime.
• Docker Label Discovery: By annotating containers with homepage.group, homepage.widget, and other metadata, services are automatically added to the dashboard without manual YAML edits.
• Webhooks & Automation: The /api/hook endpoint allows external systems (e.g., GitHub Actions, Home Assistant) to trigger dashboard updates or perform container actions.
• Custom Themes: CSS variables and SASS overrides enable full UI theming; developers can ship theme packages as separate containers or static assets.

Developer Experience

• Configuration: YAML files are concise and self‑documenting. The documentation provides a schema reference for each widget type, making onboarding fast.
• Community & Support: Active GitHub discussions, a Discord server, and continuous integration pipelines keep the project battle‑tested. The repository is MIT licensed, encouraging commercial use without licensing friction.
• Documentation Quality: The online docs are auto‑generated from Markdown, with examples for every integration. API reference pages include request/response schemas and authentication notes.

Use Cases

• Personal Productivity Hub: A developer can host a single dashboard that aggregates GitHub, Jira, and personal calendar data, all proxied securely.
• Self‑Hosted Media Center: Combine Plex, Sonarr, Radarr, and Transmission widgets into one pane, with Docker auto‑discovery simplifying updates.
• Team Ops Console: Deploy a shared dashboard that displays container health, Prometheus metrics, and Slack notifications, all accessible from a static URL behind an internal CDN.
• Learning Platform: Use the widget API to expose custom educational tools or dashboards for students, with each student’s environment isolated by separate configuration files.

Advantages

• Performance: Static generation guarantees sub‑200 ms load times; the lightweight Go API adds negligible latency.
• Flexibility: No database or backend stack is required, reducing operational overhead and attack surface.
• Licensing: MIT license removes usage restrictions, making it suitable for both open‑source and commercial deployments.