Self-Hosting Gramps Web with Docker Compose

What Is Gramps Web?

Gramps Web is the web interface for the Gramps genealogy project — the same engine that powers the Gramps Desktop application since 2001. It gives you a collaborative, browser-based platform for building family trees with interactive charts, maps, media management, and DNA analysis tools. The killer feature: bidirectional sync with Gramps Desktop, so you can edit offline and push changes to the web instance. Official site

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 2 GB of free RAM (Gramps Web is heavier than most self-hosted apps)
• 10 GB of free disk space (more if storing scanned documents and photos)
• A domain name (recommended for remote family access)

Docker Compose Configuration

Gramps Web runs three containers: the main application, a Celery background worker, and Redis for task queuing. Create a docker-compose.yml:

services:
  grampsweb:
    image: ghcr.io/gramps-project/grampsweb:26.2.0
    container_name: grampsweb
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      GRAMPSWEB_TREE: "Family Tree"                                    # Name of your tree
      GRAMPSWEB_CELERY_CONFIG__broker_url: "redis://grampsweb_redis:6379/0"
      GRAMPSWEB_CELERY_CONFIG__result_backend: "redis://grampsweb_redis:6379/0"
      GRAMPSWEB_RATELIMIT_STORAGE_URI: "redis://grampsweb_redis:6379/1"
      GRAMPSWEB_SECRET_KEY: "CHANGE-ME-generate-with-openssl-rand-hex-32"  # CHANGE THIS
    volumes:
      - gramps_users:/app/users            # User accounts database
      - gramps_index:/app/indexdir         # Full-text search index
      - gramps_thumb_cache:/app/thumbnail_cache
      - gramps_cache:/app/cache            # Export and report cache
      - gramps_secret:/app/secret          # Flask secret key
      - gramps_db:/root/.gramps/grampsdb   # Gramps genealogy database
      - gramps_media:/app/media            # Photos, documents, scans
      - gramps_tmp:/tmp
    depends_on:
      - grampsweb_redis
    networks:
      - grampsweb

  grampsweb_celery:
    image: ghcr.io/gramps-project/grampsweb:26.2.0
    container_name: grampsweb_celery
    restart: unless-stopped
    command: celery -A gramps_webapi.celery worker --loglevel=INFO --concurrency=2
    environment:
      GRAMPSWEB_TREE: "Family Tree"
      GRAMPSWEB_CELERY_CONFIG__broker_url: "redis://grampsweb_redis:6379/0"
      GRAMPSWEB_CELERY_CONFIG__result_backend: "redis://grampsweb_redis:6379/0"
      GRAMPSWEB_RATELIMIT_STORAGE_URI: "redis://grampsweb_redis:6379/1"
      GRAMPSWEB_SECRET_KEY: "CHANGE-ME-generate-with-openssl-rand-hex-32"  # Must match above
    volumes:
      - gramps_users:/app/users
      - gramps_index:/app/indexdir
      - gramps_thumb_cache:/app/thumbnail_cache
      - gramps_cache:/app/cache
      - gramps_secret:/app/secret
      - gramps_db:/root/.gramps/grampsdb
      - gramps_media:/app/media
      - gramps_tmp:/tmp
    depends_on:
      - grampsweb_redis
    networks:
      - grampsweb

  grampsweb_redis:
    image: redis:7.2.4-alpine
    container_name: grampsweb_redis
    restart: unless-stopped
    networks:
      - grampsweb

volumes:
  gramps_users:
  gramps_index:
  gramps_thumb_cache:
  gramps_cache:
  gramps_secret:
  gramps_db:
  gramps_media:
  gramps_tmp:

networks:
  grampsweb:

Generate a secret key before starting:

# Generate and replace in docker-compose.yml
openssl rand -hex 32

Start the stack:

docker compose up -d

First startup takes 1–2 minutes to initialize the database.

Initial Setup

1. Open http://your-server:5000 in your browser
2. Click Register to create the first user account (the first user becomes the tree owner)
3. Set up your email and password
4. You’ll land on an empty family tree — start adding people, or import an existing GEDCOM file

Importing a GEDCOM File

If you have an existing family tree from Ancestry, MyHeritage, or another genealogy tool:

1. Export your tree as a .ged (GEDCOM) file from the source application
2. In Gramps Web, go to the import section
3. Upload the GEDCOM file — large trees (10,000+ people) may take several minutes to process
4. Review the imported data for any conversion warnings

Configuration

Reducing Memory Usage

Gramps Web defaults to spawning Gunicorn workers equal to your CPU count. On a resource-constrained VPS, reduce both the web and Celery worker counts:

# Add to grampsweb service environment
GUNICORN_NUM_WORKERS: "2"

# Celery worker command already has --concurrency=2

With 2 workers each, idle RAM drops from ~1.5 GB to ~800 MB.

Email Notifications

For user registration and password resets, configure SMTP:

environment:
  GRAMPSWEB_EMAIL_HOST: "smtp.example.com"
  GRAMPSWEB_EMAIL_PORT: "587"
  GRAMPSWEB_EMAIL_HOST_USER: "[email protected]"
  GRAMPSWEB_EMAIL_HOST_PASSWORD: "your-smtp-password"  # CHANGE THIS
  GRAMPSWEB_EMAIL_USE_STARTTLS: "True"
  GRAMPSWEB_DEFAULT_FROM_EMAIL: "[email protected]"
  GRAMPSWEB_BASE_URL: "https://tree.example.com"

Gramps Desktop Sync

The standout feature of Gramps Web: bidirectional sync with the Gramps Desktop application.

1. Install Gramps Desktop (5.1+) on your computer
2. Install the Gramps Web Sync addon from the Gramps addon manager
3. In Gramps Desktop, go to Tools → Gramps Web Sync
4. Enter your Gramps Web URL and credentials
5. Sync pushes and pulls changes in both directions

This lets you do detailed editing in the full desktop application and share results through the web interface.

Reverse Proxy

Proxy to port 5000. Example Caddy config:

tree.example.com {
    reverse_proxy grampsweb:5000
}

Set GRAMPSWEB_BASE_URL to your public URL when behind a reverse proxy — this ensures password reset links work correctly. See Reverse Proxy Setup.

Backup

Gramps Web stores data across multiple volumes. Back up the three critical ones:

# Genealogy database (most important)
docker run --rm -v gramps_db:/data -v $(pwd):/backup \
  alpine tar czf /backup/gramps-db-$(date +%Y%m%d).tar.gz -C /data .

# Media files (photos and documents)
docker run --rm -v gramps_media:/data -v $(pwd):/backup \
  alpine tar czf /backup/gramps-media-$(date +%Y%m%d).tar.gz -C /data .

# User accounts
docker run --rm -v gramps_users:/data -v $(pwd):/backup \
  alpine tar czf /backup/gramps-users-$(date +%Y%m%d).tar.gz -C /data .

Alternatively, export your tree as a GEDCOM file periodically for a portable backup. See Backup Strategy.

Troubleshooting

GEDCOM Import Hangs on Large Trees

Symptom: Importing a GEDCOM with 10,000+ people seems stuck — the progress bar stops moving.

Fix: The import runs as a Celery background task. Check the Celery worker logs:

docker logs grampsweb_celery --tail 50

If the worker ran out of memory, increase the container’s memory limit and the --concurrency flag. For very large imports, set --concurrency=1 to reduce memory pressure.

High Memory Usage at Idle

Symptom: Gramps Web uses 1.5 GB+ RAM even with no users active.

Fix: Reduce worker counts. Add GUNICORN_NUM_WORKERS: "1" to the main service and change Celery to --concurrency=1. This brings idle usage to ~500–600 MB. The trade-off: slower concurrent request handling.

”Internal Server Error” on First Load

Symptom: 500 error immediately after docker compose up.

Fix: The first startup takes 1–2 minutes to initialize. Wait for the Celery worker to finish setup. Check logs with docker logs grampsweb — look for “Gramps Web API started” as the success signal.

Search Returns No Results

Symptom: Full-text search finds nothing even though people exist in the tree.

Fix: The search index may not have been built yet. Trigger a reindex from the admin panel, or restart the Celery worker — it rebuilds the index in the gramps_index volume on startup.

Resource Requirements

Resource	Minimum	Recommended
RAM	1 GB (single user, reduced workers)	2 GB+
CPU	1 vCPU	2 vCPU
Disk	10 GB (app + small tree)	20 GB+ (with photos)
Containers	3 (app + Celery + Redis)	3

Gramps Web is one of the heavier self-hosted apps. The 3-container stack with default settings uses ~1.5 GB RAM at idle. Budget accordingly.

Verdict

Gramps Web is the right choice if you already use Gramps Desktop or want the most feature-rich genealogy platform. The desktop sync is genuinely unique — no other self-hosted genealogy tool offers it. DNA tools, interactive maps with historical overlays, and the AI research assistant push it well beyond basic family tree software.

The downside: it’s heavy. 1.5 GB RAM idle for a genealogy app is steep, especially on a shared homelab server. And the GEDCOM import can struggle with trees over 10,000 people. If you want something lighter with better large-tree performance and stronger privacy controls, webtrees uses a fraction of the resources. For the full-featured experience with desktop sync, Gramps Web has no real competition.

Related

• Self-Hosting Webtrees with Docker
• Webtrees vs Gramps Web: Which to Self-Host?
• Best Self-Hosted Genealogy Tools
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy
• Linux Basics for Self-Hosting