# Project pack: Homepage @ 44bf8c1

Facts about **Homepage** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Homepage is a start page for your browser or a wall tablet. It gathers the links your household uses into tidy, labelled tiles, with the weather, the date, a search box and live numbers from your home apps, such as tonight's meal from Mealie or how many photos are in Immich. You set it up by editing a few simple text files, so an AI can write them for you. It runs on your own computer and keeps your app passwords out of the browser.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://gethomepage.dev
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/gethomepage/homepage
- Pinned commit: `44bf8c196232592049d99275f7c58718d167e9e4`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/gethomepage/homepage/archive/44bf8c196232592049d99275f7c58718d167e9e4.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://gethomepage.dev
- Licence: **GPL-3.0-only**. Free to use and change. If you give a changed copy to other people, you must share your source code under the same licence. Running it for yourself or your household has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/gethomepage/homepage bespoke-homepage
  cd bespoke-homepage
  git checkout --detach 44bf8c196232592049d99275f7c58718d167e9e4
  # Prepare development requirements and local configuration first.
  # Setup notes: http://localhost:3000; copy src/skeleton to config/ first
  pnpm install && pnpm dev
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  docker run -d --name homepage -p 3000:3000 -e HOMEPAGE_ALLOWED_HOSTS=localhost:3000 -v /path/to/config:/app/config --restart unless-stopped ghcr.io/gethomepage/homepage:latest
  # then open http://localhost:3000; example config files appear in /path/to/config on first start.
  # Add the address you'll use (e.g. 192.168.1.20:3000) to HOMEPAGE_ALLOWED_HOSTS.
  ```
- Tools these commands use: Docker (AMD64 or ARM64, so a Raspberry Pi works), For development, Node.js 22 and pnpm
- Develop: `pnpm install && pnpm dev   # http://localhost:3000; copy src/skeleton to config/ first`
- Test: `pnpm test`
- Check/lint: `pnpm lint`
- Build: `pnpm build`
- Stack: javascript, yaml, css (Next.js 16, React 19, Tailwind CSS, next-i18next, NextAuth, Vitest). Difficulty for a non-developer with an AI: **easy**. Everything you see is defined in a handful of YAML files (services, bookmarks, widgets, settings), with custom.css and custom.js for looks. No database. A new service widget is a small, well-documented folder in src/widgets/ with many examples to copy.
Personal data: **no**. Stored in: YAML files plus custom.css and custom.js in the config folder (/app/config in Docker). No database. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/homepage/44bf8c1/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/homepage/44bf8c1/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/homepage/44bf8c1/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/homepage/44bf8c1/r3/SKILL.md)