# Project pack: Umami @ e92fdab

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

> Umami tells you how your website is doing: how many people visited, which pages they read, where they came from and which country and device they used. It is a simple, privacy-friendly alternative to Google Analytics that uses no cookies, so you usually don't need a cookie banner. You add one line of code to your site, and Umami shows clear charts. It runs on your own server, so your visitors' data stays with you.

## 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.
- Hosted alternative, **the person's choice, never a default**: Umami Cloud (https://umami.is); cost/account: official hosted service; account and price not verified here.
- Verdict source: https://umami.is/docs/install
- 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/umami-software/umami
- Pinned commit: `e92fdab99508a8ed05249f6c5f07e140deab79e1`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/umami-software/umami/archive/e92fdab99508a8ed05249f6c5f07e140deab79e1.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://umami.is/docs
- Live demo: https://cloud.umami.is/share/LGazGOecbDtaIwDr/umami.is. Official read-only demo linked from the README, showing statistics for umami.is.
- Licence: **MIT**. Free to use, change and share for any purpose, including commercial use. Keep the copyright and licence notice if you share the code. No obligation to publish your changes.

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

  ```sh
  git clone https://github.com/umami-software/umami bespoke-umami
  cd bespoke-umami
  git checkout --detach e92fdab99508a8ed05249f6c5f07e140deab79e1
  # Prepare development requirements and local configuration first.
  # Setup notes: needs DATABASE_URL in .env; app on :3000
  pnpm install && pnpm dev
  ```

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

  ```sh
  Download docker-compose.yml from the repo, change APP_SECRET to a random string (and the database password), then run `docker compose up -d` and open http://localhost:3000. Log in as admin / umami and change the password straight away. Add your website in Settings → Websites and paste the tracking code into your site.
  ```
- Tools these commands use: Docker with Docker Compose, or Node.js 18.18+ with pnpm and PostgreSQL 12.14+
- Develop: `pnpm install && pnpm dev   # needs DATABASE_URL in .env; app on :3000`
- Test: `pnpm test`
- Check/lint: `pnpm lint`
- Build: `pnpm build`
- Stack: typescript (Next.js 16, React 19, Prisma, TanStack Query, Zustand, react-zen). Difficulty for a non-developer with an AI: **moderate**. A single Next.js app in TypeScript, so one language end to end. Most needs are covered by settings, the tracker's options, custom events, the API and share links. Code changes touch src/app/ (pages and API routes), src/queries/ (database queries with both PostgreSQL and ClickHouse versions) and src/tracker/ (the script on your site). Builds take a while.
- The project's own AI instructions, in the repository: `CONTRIBUTING.md`.
Personal data: **yes**. Stored in: PostgreSQL (the umami-db-data volume), or ClickHouse for large sites. Secrets are entered by the person, never in chat.

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