# Project pack: Gramps Web @ 81176f7

Facts about **Gramps Web** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and 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.

## Version and source
- Repository: https://github.com/gramps-project/gramps-web
- Pinned commit: `81176f7cb7208ab82b1f974df46cfcd3c6a50c8c`. Use exactly this version.
- Get it: `git clone https://github.com/gramps-project/gramps-web gramps-web && cd gramps-web && git checkout 81176f7cb7208ab82b1f974df46cfcd3c6a50c8c`
- Or download a zip: https://github.com/gramps-project/gramps-web/archive/81176f7cb7208ab82b1f974df46cfcd3c6a50c8c.zip
- 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.

## Running it
- Easiest:

  ```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).
  ```

- Needs: 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
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **users-and-roles** [settings]: Let grandparents only look, cousins add suggestions, and one or two people edit everything. → `Settings → Manage Users (roles Guest, Member, Contributor, Editor, Owner); described in the Administration → Users page of the docs`
- **tree-colours-and-settings** [settings]: Pick the family's colours for the whole tree. → `Admin settings → theme colours and tree settings (src/views/GrampsjsViewAdminSettings.js, src/theme.js)`
- **personal-preferences** [settings]: Each relative picks their own language and who the tree centres on. → `User settings → language (50+), light or dark theme, home person (src/views/GrampsjsViewSettingsUser.js, lang/)`
- **frontend-config** [settings]: Hide the DNA section, hide sign-up, or use different background maps. → `config.js at the web root, window.grampsjsConfig (src/config.js); options hideDNALink, hideRegisterLink, map styles`
- **ai-chat** [settings]: Ask questions about your tree in your own language, with a cloud model or a private local one. → `GRAMPSWEB_LLM_MODEL and GRAMPSWEB_LLM_BASE_URL on the server; chat page src/views/GrampsjsViewChat.js`
- **import-export-sync** [extend]: Bring in a tree from Ancestry or another program, and keep Gramps Desktop and the website in step. → `Import and Export pages (Gramps XML, GEDCOM, CSV, reports); Gramps Desktop sync addon`
- **api** [extend]: Scripts that add records, make printed books or check for missing dates. → `Gramps Web API REST endpoints (separate gramps-web-api repository), called from src/api.js`
- **views-and-charts** [code]: New pages, dashboard cards or chart styles. → `src/views/ (e.g. GrampsjsViewDashboard.js, GrampsjsViewTree.js), src/components/, src/charts/ (FanChart.js, TreeChart.js, Timeline.js)`
- **text** [code]: Change wording; other languages come from Weblate. → `lang/en.json for front-end text; Gramps strings in src/strings.js`

## Must keep working
- The family tree data. Export a Gramps XML backup before any change or upgrade.
- Privacy of living people and records marked private; guests and members must not see private data.
- User roles and permissions are enforced by the API; never rely on hiding things in the interface alone.
- Compatibility with Gramps Desktop and the Gramps XML format.
- Front-end strings go in lang/en.json and Gramps strings in src/strings.js, as AGENTS.md describes.

## Staying updatable
Roles, admin settings, config.js and the AI chat cover most needs without a fork. Upstream is run by very few volunteers: open an issue and wait for a reply before any pull request beyond a one-line fix. AI help is fine, but read everything before posting and post as yourself; an assistant must never write as though it were a human contributor. Server changes belong in the separate gramps-web-api repository.

## Data, costs and safety
- 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. Family trees include living people's names, birth dates and relationships. Back up the database, users and media volumes, and export a Gramps XML file regularly (Export page), which opens in Gramps Desktop too.
- Service: LLM provider (OpenAI, Mistral, Anthropic or other OpenAI-compatible APIs) (optional, pay-per-use (or free with local Ollama)): The optional AI chat that answers questions about your tree using tool calls against your database.
- Service: Ollama (local) (optional, free (uses your own hardware; a GPU helps)): Runs the AI chat model privately on your own machine.
- Service: Email (SMTP) (optional, free with most providers): Password resets and confirming new users.
- Service: Map tiles (OpenFreeMap, OpenHistoricalMap) (optional, free): Background maps and historical map overlays; changeable in the front-end config.
- Service: Gramps Web telemetry (optional, free): An anonymous daily ping with random server and tree IDs, on by default. Turn off with GRAMPSWEB_DISABLE_TELEMETRY.
- Setting `GRAMPSWEB_TREE`: Name of the family tree to open. A new empty tree with this name is created if it doesn't exist.
- Setting `GRAMPSWEB_SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Secret for signing logins. The Docker image creates one in the secret volume if unset. Never paste it into an AI chat.
- Setting `GRAMPSWEB_BASE_URL`: The address people open Gramps Web at, needed for password-reset links and notifications.
- Setting `GRAMPSWEB_REGISTRATION_DISABLED`: Set True so strangers can't request an account; invite relatives yourself.
- Setting `GRAMPSWEB_EMAIL_HOST`: Mail server for password resets. GRAMPSWEB_EMAIL_PORT, GRAMPSWEB_EMAIL_HOST_USER and GRAMPSWEB_DEFAULT_FROM_EMAIL go with it.
- Setting `GRAMPSWEB_EMAIL_HOST_PASSWORD` (**secret**: the person enters it themselves, never in chat): Mail account password.
- Setting `GRAMPSWEB_LLM_MODEL`: AI chat model, e.g. gpt-4o-mini or ollama:qwen2.5:7b. Unset means no AI chat. GRAMPSWEB_LLM_BASE_URL points at a local server.
- Setting `OPENAI_API_KEY` (**secret**: the person enters it themselves, never in chat): Only for OpenAI-hosted chat models (Mistral uses MISTRAL_API_KEY).
- Setting `GRAMPSWEB_DISABLE_TELEMETRY`: Set True to stop the anonymous daily usage ping.
- Family trees hold names, birth dates and places of living people. Keep registration disabled, use HTTPS, and give relatives the lowest role they need.
- With a cloud AI model, your question and the tree records the AI looks up are sent to that provider. Use Ollama to keep the chat on your own machine.
- Anonymous telemetry is on by default; set GRAMPSWEB_DISABLE_TELEMETRY=True to turn it off.
- Never paste the secret key, email password or API keys into an AI chat.

---

# Customising Gramps Web

Gramps Web has two halves: this repository is the **web interface** (Lit web components), and the server is the
separate **Gramps Web API** (Python). Roles, settings and a small `config.js` cover most family wishes.

## Level 1: Settings (no code)
- **Users and roles:** Settings → Manage Users. Guest and Member can look, Contributor can add, Editor can change, Owner manages users. Keep `GRAMPSWEB_REGISTRATION_DISABLED=True` and invite people yourself.
- **Tree colours:** admin settings → theme colours apply to everyone using the tree (`src/views/GrampsjsViewAdminSettings.js`).
- **Personal settings:** language (50+), light or dark theme and home person, per user.
- **`config.js`:** at the root of the served files, `window.grampsjsConfig = { hideDNALink: true, hideRegisterLink: true }`, plus map styles (`mapBaseStyleLight`, `mapBaseStyleDark`, `mapOhmStyle`).
- **AI chat:** set `GRAMPSWEB_LLM_MODEL` (e.g. `gpt-4o-mini`, or `ollama:qwen2.5:7b` with `GRAMPSWEB_LLM_BASE_URL=http://ollama:11434/v1/`). The chat answers by looking up records in your tree.
- **Server options:** `GRAMPSWEB_BASE_URL`, email (`GRAMPSWEB_EMAIL_*`), `GRAMPSWEB_DISABLE_TELEMETRY`.

## Level 2: Extend (no fork)
- **Import:** Gramps XML (best), GEDCOM from Ancestry, MyHeritage and others, CSV.
- **Export and reports:** Gramps XML backups, GEDCOM, and Gramps reports such as book reports and fan charts as PDF.
- **Gramps Desktop sync:** the Gramps Web Sync addon keeps a desktop tree and the website in step (same Gramps version on both).
- **API:** the Gramps Web API serves everything the interface does, for scripts and other tools.

## Level 3: Code
Read upstream `AGENTS.md` first (conventions: `Grampsjs` prefix, `md-*` components, `<grampsjs-icon>`).

| Change | Where |
|---|---|
| Pages | `src/views/` (e.g. `GrampsjsViewDashboard.js`, `GrampsjsViewPeople.js`) |
| Reusable pieces | `src/components/` |
| Charts | `src/charts/` (`FanChart.js`, `TreeChart.js`, `Timeline.js`) |
| Colours | `src/theme.js` |
| API calls | `src/api.js` |
| Wording | `lang/en.json` (front-end strings) or `src/strings.js` (Gramps strings) |
| Data or permissions | the separate gramps-web-api repository |

## Running locally
- **Just try it:** `docker run -p "5055:5000" -e GRAMPSWEB_TREE=new ghcr.io/gramps-project/grampsweb:latest`, then open http://localhost:5055. Changes are lost on restart.
- **Use it for real:** the `docker-compose.yml` from the Deployment guide on grampsweb.org (web app, Celery worker, Valkey and persistent volumes).
- **Develop the interface:**
  1. Run a Gramps Web API backend on port 5555 (the dev container helps).
  2. `npm install`.
  3. `npm start` and open http://localhost:8001.
- **Check:** `npm run lint`, `npm run typecheck`, `npm test`.

## Pitfalls
- Export a Gramps XML file before upgrades or experiments. Sync is not a backup.
- Hiding something in the interface is not privacy; the API enforces roles and private records.
- Keep Gramps Desktop and the server on the same Gramps version when syncing.
- Upstream is a small volunteer team: open an issue and wait before sending a pull request, and post as yourself, not as an AI.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/gramps-web/81176f7/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/gramps-web/81176f7/SKILL.md)