Pull your Ancestry.com family tree, photos, and sources directly into your self-hosted ɳFamily instance. One-time import or scheduled sync — your data, on your server.
Requires nself-family to be installed first. The importer maps Ancestry person records and relationships to the local family schema — it does not create a parallel tree.
nself license set nself_pro_...
nself plugin install family family-ancestry
nself build
nself startnself-family-ancestry connects to the Ancestry.com API using OAuth 2.0. On first run it fetches the authenticated user's primary tree, maps each person record to np_family_members, and writes relationships to np_family_relationships. Media attachments (photos, documents) are downloaded into MinIO under the family-photos bucket if nself-photos is also installed.
Sources attached to Ancestry facts are stored in np_ancestry_sources with the original citation text and a link back to the Ancestry record ID. This lets you see where a fact came from without requiring the reader to have an Ancestry account.
After the initial import, a configurable sync interval polls the Ancestry tree for changes. Additions and edits are merged; deletions are flagged for manual review rather than automatically removed — the plugin never silently drops a person from your local tree.
| Variable | Required | Default | Description |
|---|---|---|---|
PLUGIN_ANCESTRY_CLIENT_ID | Yes | — | OAuth client ID from the Ancestry Developer Portal |
PLUGIN_ANCESTRY_CLIENT_SECRET | Yes | — | OAuth client secret |
PLUGIN_ANCESTRY_SYNC_INTERVAL_HOURS | No | 24 | How often to poll for tree changes. Set to 0 to disable automatic sync. |
PLUGIN_ANCESTRY_IMPORT_MEDIA | No | true | Download photos and documents into MinIO. Requires nself-photos. |
PLUGIN_ANCESTRY_IMPORT_SOURCES | No | true | Store source citations in np_ancestry_sources |
PLUGIN_ANCESTRY_DELETION_STRATEGY | No | flag | What to do when a person is removed from the Ancestry tree: flag (mark for manual review) or archive (soft-delete locally) |
| Endpoint | Method | Description |
|---|---|---|
/ancestry/auth | GET | Begin OAuth 2.0 authorization flow. Redirects to Ancestry login. |
/ancestry/callback | GET | OAuth callback. Stores tokens and triggers first import. |
/ancestry/import | POST | Trigger a manual import. Body: { tree_id? } (defaults to primary tree) |
/ancestry/status | GET | Last sync time, person count, pending review items |
/ancestry/review | GET | List persons flagged for deletion review |
/ancestry/review/:id | POST | Resolve a deletion flag. Body: { action: "keep" | "archive" } |
/health | GET | Plugin health check |
| Table | Purpose |
|---|---|
np_ancestry_tokens | OAuth access + refresh tokens per authenticated user |
np_ancestry_person_map | Maps Ancestry person IDs to local np_family_members IDs |
np_ancestry_sources | Source citations: person_id, fact_type, citation_text, ancestry_source_id, url |
np_ancestry_sync_log | Import history: started_at, finished_at, persons_added, persons_updated, errors |
np_ancestry_deletion_queue | Persons removed from Ancestry tree, pending local review |
| Event | Payload |
|---|---|
ancestry.import.completed | Persons added, updated, flagged; sync duration; tree ID |
ancestry.person.flagged | Local member ID, Ancestry person ID, flag reason |
ancestry.auth.revoked | User ID — sync paused until re-auth |
After authorizing with Ancestry, trigger an import and watch the family graph populate:
# 1. Open the OAuth flow in your browser
open https://your-nself-host/ancestry/auth
# 2. After redirect, trigger a manual import for a specific tree
curl -X POST https://your-nself-host/ancestry/import \
-H 'Authorization: Bearer <token>' \
-d '{"tree_id": "12345678"}'
# 3. Check import status
curl https://your-nself-host/ancestry/status \
-H 'Authorization: Bearer <token>'| Feature | nself-family-ancestry | Ancestry.com only | Manual GEDCOM export |
|---|---|---|---|
| Self-hosted data | Yes — your VPS | No — Ancestry servers | Yes (one-time snapshot) |
| Automatic sync | Yes (configurable interval) | N/A | No |
| Source citations kept | Yes | Yes (in Ancestry only) | Partial (GEDCOM NOTE) |
| Media import | Yes (into MinIO) | Yes (in Ancestry only) | No |
| Symptom | Fix |
|---|---|
| OAuth callback returns 400 | The redirect URI registered in the Ancestry Developer Portal must exactly match https://your-host/ancestry/callback. Trailing slashes matter. |
| Import stalls at media download | Check MinIO is running (nself status) and PLUGIN_ANCESTRY_IMPORT_MEDIA=true. Disable media import temporarily to confirm the tree data imports cleanly. |
| Persons appear in deletion queue immediately | The Ancestry API returns a subset of persons on partial responses. Run a full import with POST /ancestry/import to reconcile before acting on the queue. |
Port: 3830 | Bundle: ɳFamily ($0.99/mo) or ɳSelf+ ($3.99/mo) | Last Updated: May 2026 | Plugin Version 1.0.13