# Project pack: Gramps Web @ 81176f7

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

> Gramps Web is a private website for your family history. Add people, dates, places, photos and sources, and see them as family tree charts, fan charts, timelines and maps. Invite relatives to look or help edit, write up stories in its blog, and optionally ask an AI questions such as "where was Grandad born?". It works together with the Gramps desktop program and runs on your own server, so your family's details stay private.

## 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://www.grampsweb.org
- 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/gramps-project/gramps-web
- Pinned commit: `81176f7cb7208ab82b1f974df46cfcd3c6a50c8c`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/gramps-project/gramps-web/archive/81176f7cb7208ab82b1f974df46cfcd3c6a50c8c.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://www.grampsweb.org
- Live demo: https://demo.grampsweb.org (username and password are the same: owner, editor, contributor or member). Official shared demo. AI chat is not available there. Don't enter real family details.
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (for example relatives outside your household), you must offer them your source code under the same licence. Running it unchanged, or for yourself, has no extra obligations.

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

  ```sh
  git clone https://github.com/gramps-project/gramps-web bespoke-gramps-web
  cd bespoke-gramps-web
  git checkout --detach 81176f7cb7208ab82b1f974df46cfcd3c6a50c8c
  # Prepare development requirements and local configuration first.
  # Setup notes: http://localhost:8001; expects the API at http://localhost:5555
  npm install && npm start
  ```

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

  ```sh
  docker run -p "5055:5000" -e GRAMPSWEB_TREE=new ghcr.io/gramps-project/grampsweb:latest
  # try it at http://localhost:5055: create the admin user and import a Gramps XML or GEDCOM file.
  # This test setup forgets changes on restart; for real use, run the docker-compose.yml from the
  # Deployment guide on grampsweb.org (web app, Celery worker and Valkey, with persistent volumes).
  ```
- Tools these commands use: Docker with Docker Compose, About 2 GB RAM (more for AI chat with a local model), For front-end development, Node.js and npm, plus a running Gramps Web API backend
- Develop: `npm install && npm start   # http://localhost:8001; expects the API at http://localhost:5555`
- Test: `npm test`
- Check/lint: `npm run lint && npm run typecheck`
- Build: `npm run build   # static files in dist/`
- Stack: javascript, typescript, python (Lit (Web Components), Material Web Components, D3.js, MapLibre GL, Rollup, Vitest, Gramps Web API (Flask, separate repo)). Difficulty for a non-developer with an AI: **moderate**. This repository is the web interface only (Lit web components in src/). The server is the separate Gramps Web API repository (Python), which uses the Gramps desktop libraries. Settings, theme colours and front-end options cover a lot; interface changes are plain JavaScript and approachable with AGENTS.md, but anything about data means changing the API too.
- The project's own AI instructions, in the repository: `AGENTS.md`, `CLAUDE.md`.
Personal data: **yes**. Stored in: The family tree in a Gramps database (gramps_db volume, SQLite by default; PostgreSQL optional), user accounts in a separate user database (gramps_users), photos and documents in gramps_media, plus search index and caches. Secrets are entered by the person, never in chat.

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