Onboarding: gethomepage/homepage

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gethomepage/homepage shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit today
• 11 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gethomepage/homepage repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gethomepage/homepage.

What it runs against: a local clone of gethomepage/homepage — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gethomepage/homepage | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>gethomepage/homepage</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gethomepage/homepage. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gethomepage/homepage.git
#   cd homepage
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gethomepage/homepage and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gethomepage/homepage(\\.git)?\\b" \\
  && ok "origin remote is gethomepage/homepage" \\
  || miss "origin remote is not gethomepage/homepage (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f ".github/workflows/docker-publish.yml" \\
  && ok ".github/workflows/docker-publish.yml" \\
  || miss "missing critical file: .github/workflows/docker-publish.yml"
test -f "docs/configs/services.md" \\
  && ok "docs/configs/services.md" \\
  || miss "missing critical file: docs/configs/services.md"
test -f "docs/widgets/authoring/index.md" \\
  && ok "docs/widgets/authoring/index.md" \\
  || miss "missing critical file: docs/widgets/authoring/index.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gethomepage/homepage"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Homepage is a Next.js-based customizable startpage/application dashboard that aggregates 100+ service integrations (Radarr, Sonarr, Docker, Kubernetes, etc.) with automatic discovery via Docker labels and YAML configuration. It's a fully static, security-focused homepage builder where all API requests to backend services are proxied to hide credentials, generating fast load times and maintaining a modern UI with internationalization support for 40+ languages. Monolithic Next.js application with pages/ structure for API routes and frontend. Configuration ingested from YAML files and Docker labels; services defined via integration files. State managed client-side via SWR for data fetching. Codebase is 2M+ JavaScript lines suggesting large surface area organized by feature (likely services/, widgets/, components/ directories not fully listed). Docker image published via Dockerfile; dev container provided in .devcontainer/.

Who it's for

Self-hosted infrastructure enthusiasts and homelab administrators who want a unified dashboard for monitoring multiple services (Docker containers, *arr apps, game servers, Kubernetes clusters) without exposing API keys, plus developers contributing to open-source dashboard/widget systems.

Maturity & risk

Production-ready and actively developed. Version 1.12.3 with comprehensive CI/CD via GitHub Actions (docker-publish.yml, test.yml, lint.yml), codecov coverage tracking, and an established contributor community (evidenced by .all-contributorsrc and Crowdin translation integration). Regular releases via release-drafter.yml indicate steady maintenance.

Moderate risk from large dependency surface: 30+ direct dependencies including dockerode, @kubernetes/client-node, gamedig, and various service-specific libraries increase attack surface. No apparent single-maintainer bottleneck based on contributor infrastructure. Watch for breaking changes in Next.js (currently v16.2.4) and i18next ecosystem. Dependency management via pnpm (enforced in preinstall script) reduces lock file conflicts but requires pnpm familiarity.

Active areas of work

Active development on Next.js 16.x upgrade, i18n expansion (Crowdin workflow), and Docker/Kubernetes integration improvements. CI pipeline robust with pr-quality and lint checks. No specific milestone data visible, but release-drafter.yml suggests semantic versioning workflow in place.

Get running

git clone https://github.com/gethomepage/homepage.git
cd homepage
pnpm install
pnpm dev

Dev server runs on http://localhost:3000 via Next.js dev server. Use .devcontainer for standardized environment with setup.sh initialization.

Daily commands:

pnpm dev          # Next.js dev server on :3000
pnpm build        # Webpack build
pnpm start        # Production mode (requires build first)
pnpm lint         # ESLint check
pnpm test         # Vitest unit tests
pnpm test:watch   # Vitest with file watch

Or via Docker: docker build -t homepage . && docker run -p 3000:3000 homepage.

Map of the codebase

• package.json — Declares all runtime dependencies (Next.js, Dockerode, Kubernetes client, i18n) and build scripts—essential for understanding the project's tech stack and development workflow.
• Dockerfile — Production container definition that bundles the Next.js app, shows how the application is deployed, and illustrates the runtime environment.
• .github/workflows/docker-publish.yml — CI/CD pipeline for building and publishing Docker images—critical for understanding release, deployment, and versioning processes.
• docs/configs/services.md — Configuration documentation for service integrations (100+ services)—developers must understand the service plugin architecture and YAML schema before adding new services.
• docs/widgets/authoring/index.md — Entry point for widget authoring—essential guide for extending Homepage with custom information panels and API integrations.
• docker-entrypoint.sh — Startup script that initializes the application, handles configuration loading, and Docker/Kubernetes discovery—reveals core initialization flow.
• docs/installation/docker.md — Primary deployment documentation covering Docker Compose and volumes—shows how users configure the application and why certain architectural decisions were made.

How to make changes

Add a New Service Integration

1. Review the service architecture in docs/configs/services.md to understand the required fields (name, url, icon, description, widget type). (docs/configs/services.md)
2. Create a new API route handler in the Next.js app/api/services directory (or similar) to proxy requests to the target service's API. (package.json)
3. Update docs/configs/services.md with the new service configuration block, including example YAML and required/optional fields. (docs/configs/services.md)
4. If the service has a custom widget, create the React component following the widget authoring pattern in docs/widgets/authoring/component.md. (docs/widgets/authoring/component.md)
5. Add i18n keys for the service name and UI strings by updating translation files and registering with Crowdin (crowdin.yml). (crowdin.yml)
6. Write tests for the API handler and widget using Vitest (as configured in package.json). (package.json)

Add a New Info Widget

1. Start with the widget authoring guide at docs/widgets/authoring/getting-started.md to understand component structure and metadata requirements. (docs/widgets/authoring/getting-started.md)
2. Create a new React component following the pattern in docs/widgets/authoring/component.md, implementing the required props and hooks. (docs/widgets/authoring/component.md)
3. If the widget fetches data from an external service, follow the API proxy pattern in docs/widgets/authoring/api.md. (docs/widgets/authoring/api.md)
4. Document the widget in docs/widgets/info/ with configuration examples and screenshots. (docs/widgets/info/index.md)
5. Add translations for all UI strings using i18next patterns and register keys in crowdin.yml. (crowdin.yml)
6. Create unit tests for the widget component in the test suite (package.json vitest config). (package.json)

Deploy Homepage to Kubernetes

1. Review the Kubernetes integration documentation at docs/installation/k8s.md and docs/configs/kubernetes.md to understand service discovery and permissions. (docs/installation/k8s.md)
2. Build the Docker image using the Dockerfile (or use the pre-built image from GitHub Container Registry published by docker-publish.yml). (Dockerfile)
3. Create a Kubernetes Deployment manifest using the container image, mounting a ConfigMap for config.yml and PVC for persistent user data. (docs/installation/k8s.md)
4. Configure service discovery by granting the Homepage pod RBAC permissions to list and watch Kubernetes resources (documented in docs/configs/kubernetes.md). (docs/configs/kubernetes.md)
5. Mount the config.yml ConfigMap and verify the application starts via docker-entrypoint.sh initialization. (docker-entrypoint.sh)

Customize Homepage with CSS, JavaScript, and Bookmarks

1. Review the customization options in docs/configs/custom-css-js.md to understand where to inject custom styles and scripts. (docs/configs/custom-css-js.md)
2. Create a config.yml file (mounted in Docker or placed in /app/config) with your dashboard sections, services, and bookmarks following docs/configs/bookmarks.md. (docs/configs/bookmarks.md)
3. Add custom CSS/JS files to the config directory and reference them in config.yml; these are loaded by the Next.js app during rendering. (docs/configs/custom-css-js.md)
4. Test your configuration by running the app locally (npm run dev from package.json) or via Docker, verifying the layout and service widgets render correctly. (package.json)

Why these technologies

• Next.js (React SSR/SSG) — Provides static-friendly rendering for fast dashboard load times, API routes for service proxying, and built-in optimization (image, code splitting). Supports both server-side and client-side data fetching.
• Dockerode & Kubernetes client-node — Native Node.js SDKs for Docker and Kubernetes APIs; enables automatic service discovery from container labels and cluster resources without external agents or webhooks.
• i18next + Crowdin — Decouples translation strings from code; Crowdin integration allows community-driven multilingual support at scale without

Traps & gotchas

pnpm enforcement: preinstall script runs npx only-allow pnpm — npm/yarn installs will fail. Docker socket access: Docker integration requires /var/run/docker.sock mounted in container (standard but easy to forget). Environment variables for services: Each service integration likely requires API keys/credentials passed as env vars or config file (check docs for specifics per service). Next.js webpack flag: Build command uses --webpack flag explicitly; implies custom webpack config or Turbopack opt-out. Crowdin sync: Translations managed externally; modifying en locale JSON files may conflict with Crowdin pull requests. Python version: .python-version file present (likely for dev tooling or pre-commit hooks); check .pre-commit-config.yaml for required Python setup.

Architecture

Concepts to learn

• API request proxying for credential hiding — Homepage's core security model: all requests to external services are proxied through the server to prevent frontend JavaScript from exposing API keys; understanding this pattern is essential to adding new service integrations safely.
• Docker label-based service discovery — Enables automatic registration of containerized services without manual YAML configuration; a key differentiator. Requires understanding Docker SDK and label parsing patterns.
• Static site generation (SSG) at build time — Next.js generates static HTML at build time for instant load; Homepage leverages this for performance-critical dashboard, reducing runtime computation.
• Service widget plugin architecture — Homepage supports 100+ service integrations via a plugin pattern (likely configuration-driven); understanding how to add new service widgets (Sonarr, Radarr, Kubernetes, etc.) is the primary contribution path.
• i18n (Internationalization) with Crowdin — Homepage supports 40+ languages via external Crowdin project. New contributors must understand how to manage locale files and avoid breaking Crowdin sync workflows.
• SWR (stale-while-revalidate) client-side data fetching — SWR is used for polling service status and stats; understanding cache invalidation and background revalidation is critical for responsive widget updates.
• Docker multi-architecture image builds — Homepage publishes AMD64 and ARM64 images. The CI/CD leverages buildx for cross-arch compilation; relevant for contributors modifying Dockerfile or build process.

Related repos

• MichaIng/DietPi — DietPi dashboard and management UI also target lightweight self-hosted deployments; same user base and design philosophy.
• awesome-selfhosted/awesome-selfhosted — Curated list of self-hosted applications that Homepage integrates with; primary reference for which services to prioritize.
• Portainer/Portainer — Alternative Docker UI/dashboard; overlaps in containerization monitoring but Homepage is simpler and dashboarding-focused vs. Portainer's management scope.
• synology-community/SynoCommunitypkg — Community packages for Synology NAS (common Homepage deployment target); cross-referenced deployment platform.
• k8s-at-home/helm-charts — Helm charts for self-hosted apps that Homepage monitors; indicates ecosystem of Kubernetes-native applications driving feature requests.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive widget integration tests for service API modules

The repo has 100+ service integrations (docker, kubernetes, proxmox, etc.) but lacks dedicated test coverage for widget/service API adapters. Looking at the dependencies (dockerode, @kubernetes/client-node, gamedig, minecraftstatuspinger), there are multiple integration points that need unit tests to prevent regressions when service APIs change. This would significantly improve code quality and catch breaking changes early.

• [ ] Create test/widgets/ directory structure mirroring src/widgets structure
• [ ] Add unit tests for docker.ts, kubernetes.ts, proxmox.ts service modules
• [ ] Mock external service APIs (Docker daemon, K8s API, Proxmox API) using vitest mocking
• [ ] Test error handling and timeout scenarios for each service integration
• [ ] Add test:coverage command verification showing >80% coverage for service modules
• [ ] Reference existing test setup in package.json (vitest, @testing-library/react)

Create missing deployment validation GitHub Action workflow

The repo has docker-publish.yml, docs-publish.yml, and test.yml workflows, but lacks a pre-deployment validation workflow. Given this is a dashboard that users self-host via Docker and Kubernetes, a workflow that validates Docker image buildability, Kubernetes manifests syntax, and runs a smoke test on built images would catch deployment issues before they reach users.

• [ ] Create .github/workflows/deployment-validation.yml
• [ ] Add step to validate Dockerfile with hadolint or similar linter
• [ ] Add step to test Docker image build with both Dockerfile and Dockerfile-tilt
• [ ] Add step to validate Kubernetes installation examples in docs/installation/k8s.md
• [ ] Add step to run basic container health checks (curl localhost:3000, check /etc/os-release)
• [ ] Trigger on: pull_request (for PRs affecting Dockerfile/k8s docs) and release workflow

Add missing service configuration validation tests and docs for YAML schema

The repo heavily relies on YAML configuration (services.md, bookmarks.md, settings.md), but lacks formalized schema validation and comprehensive test coverage for configuration parsing. Users report configuration issues in discussions, but there's no way to validate configs before deployment. Adding JSON Schema validation with tests would reduce user friction.

• [ ] Create src/schemas/ directory with JSON Schema files for services.yaml, bookmarks.yaml, settings.yaml
• [ ] Implement YAML validator utility using a library like ajv
• [ ] Add test/config/ with vitest tests validating schema against docs/configs examples
• [ ] Create docs/configs/schema-reference.md documenting the JSON Schema format
• [ ] Add CLI validation tool (npm run validate:config) that users can run locally
• [ ] Reference existing js-yaml dependency for parsing

Good first issues

• Add unit tests for service integrations: Currently no __tests__ directory visible in the file list. Create tests for at least 3 service clients (e.g., Docker, Kubernetes, Radarr) using Vitest + @testing-library/react pattern; target 70%+ coverage for pages/api/services/.
• Document Docker label discovery with examples: README lacks concrete Docker Compose examples showing how to auto-discover services via labels (e.g., labels: { 'homepage.group': 'Media', 'homepage.name': 'Radarr' }). Add a DOCKER_DISCOVERY.md file with 3+ runnable examples.
• Add missing TypeScript types for service plugins: Codebase is JavaScript but has 2M+ LOC; create a minimal src/types/services.ts file defining plugin interface (name, icon, color, endpoint, credentials schema) to enable future TypeScript migration and improve IDE autocomplete for contributor experience.

Top contributors

• @dependabot[bot] — 47 commits
• @shamoon — 41 commits
• @github-actions[bot] — 3 commits
• @stevenharris-dev — 2 commits
• @jimstrang — 1 commits

Recent commits

• 72b0e49 — Enhancement: Normalize non-200 proxy responses to error JSON (#6630) (shamoon)
• ffb264c — Chore(deps): Bump next from 16.2.3 to 16.2.4 (#6622) (dependabot[bot])
• cd6e708 — Chore(deps): Bump react from 19.2.4 to 19.2.5 (#6621) (dependabot[bot])
• 4e621ae — Chore(deps-dev): Bump @eslint/js from 9.39.2 to 9.39.4 (#6623) (dependabot[bot])
• 93364b6 — Chore(deps): Bump json-rpc-2.0 from 1.7.0 to 1.7.1 (#6624) (dependabot[bot])
• 3dffc38 — Chore(deps): Bump @headlessui/react from 2.2.9 to 2.2.10 (#6620) (dependabot[bot])
• b2a52ff — Chore(deps): Bump pnpm/action-setup from 5.0.0 to 6.0.3 (#6614) (dependabot[bot])
• 081b9ec — Chore(deps): Bump crowdin/github-action from 2.16.0 to 2.16.2 (#6615) (dependabot[bot])
• 977be86 — Chore(deps): Bump actions/setup-node from 6.3.0 to 6.4.0 (#6613) (dependabot[bot])
• 77c9ac4 — Fix: add missing backdrop blur classes to safelist (#6617) (shamoon)

Security observations

• High · Outdated Node.js Version in Docker — Dockerfile (lines using node:22-slim and node:22-alpine). The Dockerfile uses node:22-slim and node:22-alpine as base images. Node.js 22 is an active LTS version, but regular security patching is required. Using specific version tags without pinning patch versions could lead to inconsistent builds. Fix: Pin to specific patch versions (e.g., node:22.11.0-slim) and implement automated dependency scanning. Consider using Node.js security advisories monitoring.
• High · Insecure Default in CI/CD Conditional Logic — Dockerfile (builder stage, lines with CI conditional). The Dockerfile conditionally skips dependency installation when CI=true, relying on 'prebuilt app from CI context'. This could allow compromised or modified artifacts to be included in the final image if the CI pipeline is compromised or artifacts are tampered with. Fix: Implement artifact verification using checksums/signatures. Ensure CI/CD environment is hardened with proper secret management and access controls. Consider always verifying dependencies rather than skipping installation.
• High · Known Vulnerable Dependency: follow-redirects — package.json (dependencies: follow-redirects). The package 'follow-redirects@^1.16.0' has known security vulnerabilities (CVE-2023-26159 - incorrect handling of HTTPS redirects to HTTP). The caret (^) allows patch/minor updates but may not include critical security fixes promptly. Fix: Update to follow-redirects@^1.15.6 or higher. Implement regular security audits using 'npm audit' or 'pnpm audit' in CI/CD pipeline with fail on critical vulnerabilities.
• High · Potential XXE/XML Injection Risk — package.json (dependencies: xml-js). The dependency 'xml-js@^1.6.11' is used for XML parsing. Without proper input validation and DTD/XXE protections configured, this could be vulnerable to XML External Entity (XXE) attacks if parsing untrusted XML data. Fix: Disable DTD processing and external entity resolution. Validate all XML inputs before parsing. Review all usages of xml-js in the codebase for security-sensitive operations.
• Medium · Dependency Version Ranges Using Caret (^) — package.json (most dependencies). Many dependencies use caret (^) versioning which allows automatic minor and patch version updates. This increases the attack surface as third-party dependencies could introduce vulnerabilities in updates without explicit review. Fix: Consider using tilde (~) for more conservative updates, or pin exact versions for security-critical dependencies. Implement automated dependency scanning and require explicit approval for updates.
• Medium · Multiple Service Integrations Without Validation Framework — docs/configs/ directory (docker.md, kubernetes.md, proxmox.md, etc.). The codebase integrates with 100+ external services (Docker, Kubernetes, Proxmox, etc.) via APIs. Without explicit mention of input validation, authentication verification, or rate limiting in the file structure, there's potential for SSRF, credential leakage, or DoS attacks. Fix: Implement strict input validation for all service configurations. Use network policies to restrict outbound connections. Implement credential rotation and secure storage mechanisms. Add rate limiting on API calls to integrated services.
• Medium · Kubernetes Client Library Integration — package.json (dependencies: @kubernetes/client-node). The '@kubernetes/client-node@^1.0.0' dependency allows direct Kubernetes cluster access. If improperly configured or exposed, this could allow attackers to compromise the entire Kubernetes cluster. Fix: Implement RBAC with minimal required permissions. Use service account tokens with restricted scopes. Ensure Kubernetes API endpoint is not exposed publicly. Implement audit logging for all Kubernetes API calls.
• Medium · Docker API Access Without Documented Security Controls — package.json (dependencies: dockerode). The 'dockerode@^4.0.10' dependency provides direct Docker daemon access. The Docker socket exposure or improper access controls could allow container escape or system compromise. Fix: Bind Docker socket to non-root user. Use authentication tokens. Implement resource limits and

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.