Deploying Gramps Web

Introduction

Gramps Web is a free, open-source genealogy platform that brings your family tree to the web. Built as a companion to the popular Gramps desktop application, Gramps Web allows you to collaboratively build, view, and share your family history from any device with full control over your data and privacy.

With features like interactive family tree charts, mapping tools, and support for over 40 languages, Gramps Web transforms genealogical research into an accessible, shareable experience. The platform is fully interoperable with Gramps Desktop, allowing you to sync your research seamlessly.

Key highlights of Gramps Web:

Full Privacy Control: Self-hosted with your data on your terms
Collaborative Editing: Multiple users can contribute to the family tree
Interactive Charts: Explore ancestor, descendant, fan, and hourglass charts
Mapping Tools: Visualize places on interactive maps
Media Support: Store and view photos, documents, and other media
Multi-Language: Support for 40+ languages
AI Chat Assistant: Chat with your family tree in your language
Gramps Desktop Sync: Full interoperability with the desktop application
GEDCOM Support: Import and export standard genealogy files
100% Open Source: Licensed under AGPL-3.0

This guide walks through deploying Gramps Web on Klutch.sh using Docker, configuring your genealogy database, and sharing your family history online.

Why Deploy Gramps Web on Klutch.sh

Deploying Gramps Web on Klutch.sh provides several advantages for genealogy:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gramps Web without complex orchestration. Push to GitHub and your genealogy platform deploys automatically.

Persistent Storage: Attach persistent volumes for your family tree database and media files. Your research survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure access to family data.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your tree size and media storage needs.

Custom Domains: Assign a custom domain for your family tree.

Always-On Availability: Your family history remains accessible 24/7 to family members worldwide.

Prerequisites

Before deploying Gramps Web on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Gramps Web configuration
Basic familiarity with Docker and containerization concepts
(Optional) A GEDCOM file or Gramps database to import
(Optional) Gramps Desktop for advanced editing

Understanding Gramps Web Architecture

Gramps Web is built on several components:

Gramps Backend: Python-based backend using the Gramps genealogy engine.

Web API: RESTful API providing access to genealogical data.

Web Frontend: Modern JavaScript frontend for viewing and editing.

SQLite/PostgreSQL: Database storage for genealogical data.

Media Storage: File storage for photos, documents, and other media.

Preparing Your Repository

To deploy Gramps Web on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

gramps-web-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/gramps-project/grampsweb:latest

# Set environment variables
ENV GRAMPSWEB_TREE=Family Tree
ENV GRAMPSWEB_SECRET_KEY=${GRAMPSWEB_SECRET_KEY}
ENV GRAMPSWEB_USER_DB_URI=sqlite:///users/users.sqlite
ENV GRAMPSWEB_MEDIA_BASE_DIR=/app/media
ENV GRAMPSWEB_SEARCH_INDEX_DIR=/app/indexdir
ENV GRAMPSWEB_STATIC_PATH=/app/static
ENV GRAMPSWEB_EMAIL_HOST=${GRAMPSWEB_EMAIL_HOST}
ENV GRAMPSWEB_EMAIL_PORT=${GRAMPSWEB_EMAIL_PORT:-587}
ENV GRAMPSWEB_EMAIL_HOST_USER=${GRAMPSWEB_EMAIL_HOST_USER}
ENV GRAMPSWEB_EMAIL_HOST_PASSWORD=${GRAMPSWEB_EMAIL_HOST_PASSWORD}
ENV GRAMPSWEB_DEFAULT_FROM_EMAIL=${GRAMPSWEB_DEFAULT_FROM_EMAIL}

# Create necessary directories
RUN mkdir -p /app/media /app/indexdir /app/users /root/.gramps/grampsdb

# Expose the web interface port
EXPOSE 5000

# The base image includes the default entrypoint

Advanced Dockerfile

For more configuration options:

FROM ghcr.io/gramps-project/grampsweb:latest

# Basic Configuration
ENV GRAMPSWEB_TREE=Family Tree
ENV GRAMPSWEB_SECRET_KEY=${GRAMPSWEB_SECRET_KEY}
ENV GRAMPSWEB_BASE_URL=${GRAMPSWEB_BASE_URL}

# Database Configuration
ENV GRAMPSWEB_USER_DB_URI=sqlite:///users/users.sqlite

# Storage Configuration
ENV GRAMPSWEB_MEDIA_BASE_DIR=/app/media
ENV GRAMPSWEB_SEARCH_INDEX_DIR=/app/indexdir

# Email Configuration (optional)
ENV GRAMPSWEB_EMAIL_HOST=${GRAMPSWEB_EMAIL_HOST}
ENV GRAMPSWEB_EMAIL_PORT=${GRAMPSWEB_EMAIL_PORT:-587}
ENV GRAMPSWEB_EMAIL_HOST_USER=${GRAMPSWEB_EMAIL_HOST_USER}
ENV GRAMPSWEB_EMAIL_HOST_PASSWORD=${GRAMPSWEB_EMAIL_HOST_PASSWORD}
ENV GRAMPSWEB_DEFAULT_FROM_EMAIL=${GRAMPSWEB_DEFAULT_FROM_EMAIL}

# Create directories
RUN mkdir -p /app/media /app/indexdir /app/users /root/.gramps/grampsdb

# Health check
HEALTHCHECK --interval=60s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:5000/api/health || exit 1

# Expose port
EXPOSE 5000

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`GRAMPSWEB_TREE`	No	Family Tree	Name of your family tree
`GRAMPSWEB_SECRET_KEY`	Yes	-	Secret key for session encryption
`GRAMPSWEB_BASE_URL`	No	-	Base URL of your instance
`GRAMPSWEB_USER_DB_URI`	No	sqlite	User database connection string
`GRAMPSWEB_MEDIA_BASE_DIR`	No	/app/media	Media file storage directory
`GRAMPSWEB_SEARCH_INDEX_DIR`	No	/app/indexdir	Search index directory
`GRAMPSWEB_EMAIL_HOST`	No	-	SMTP server for notifications
`GRAMPSWEB_EMAIL_PORT`	No	587	SMTP port
`GRAMPSWEB_EMAIL_HOST_USER`	No	-	SMTP username
`GRAMPSWEB_EMAIL_HOST_PASSWORD`	No	-	SMTP password
`GRAMPSWEB_DEFAULT_FROM_EMAIL`	No	-	From address for emails

Deploying Gramps Web on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gramps Web:

Generate a Secret Key

Generate a secure secret key for session encryption:

python3 -c "import secrets; print(secrets.token_hex(32))"

Save this key securely for the environment variables step.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Gramps Web deployment configuration"
git remote add origin https://github.com/yourusername/gramps-web-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “gramps-web” or “family-tree”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gramps Web Dockerfile.

Configure HTTP Traffic

Gramps Web serves its interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 5000

Set Environment Variables

In the environment variables section, add:

Variable	Value
`GRAMPSWEB_TREE`	Your family tree name
`GRAMPSWEB_SECRET_KEY`	Your generated secret key
`GRAMPSWEB_BASE_URL`	`https://your-app-name.klutch.sh`

For email notifications, add SMTP configuration.

Attach Persistent Volumes

Persistent storage is essential for Gramps Web. Add the following volumes:

Mount Path	Recommended Size	Purpose
`/root/.gramps/grampsdb`	5 GB	Gramps database files
`/app/users`	1 GB	User accounts database
`/app/media`	50 GB	Photos, documents, and media files
`/app/indexdir`	2 GB	Search index

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the Gramps Web container
Provision an HTTPS certificate

Create Your First User

After deployment, create your admin user. Access the registration page at https://your-app-name.klutch.sh/api/users/-/registration?role=4 (role 4 is owner).

Access Gramps Web

Once setup completes, access your Gramps Web instance at https://your-app-name.klutch.sh.

Initial Setup

Creating the First User

The first user should be created with owner privileges:

Navigate to the registration URL with role parameter
Fill in your user details
Confirm your email if SMTP is configured
Log in to access the dashboard

Importing Existing Data

If you have an existing family tree:

From GEDCOM File:

Log in as owner
Navigate to Import
Upload your GEDCOM file
Review and confirm the import

From Gramps Desktop:

Export your tree from Gramps Desktop
Import the backup file into Gramps Web
Or use the Gramps Web Sync addon for live sync

Configuring User Roles

Gramps Web supports multiple user roles:

Role	Description
Guest	View-only access to public data
Member	View private data
Contributor	Add and edit data
Editor	Full editing rights
Owner	Full admin access

Using Gramps Web

Navigating the Family Tree

Explore your genealogy:

People: Browse individuals with filtering and search
Families: View family units and relationships
Events: Track births, marriages, deaths, and more
Places: Map locations in your family history
Media: View photos and documents

Interactive Charts

Visualize relationships with charts:

Ancestor Chart: See direct ancestors
Descendant Chart: View descendants of a person
Fan Chart: Circular visualization of ancestry
Hourglass Chart: Combined ancestor/descendant view

Using Maps

Explore geographic data:

Navigate to Places
Click on the map view
See where your ancestors lived
Click markers for details

Adding People

Add individuals to your tree:

Click Add > Person
Enter basic information (name, birth, death)
Add events, attributes, and relationships
Upload photos and documents
Save the record

Connecting Relationships

Link people together:

Open a person’s record
Navigate to Family
Add parents, spouse, or children
Create or link existing family records

Syncing with Gramps Desktop

Using the Web API Sync Addon

For bi-directional sync with Gramps Desktop:

Install the Web API Sync addon in Gramps Desktop
Configure the connection to your Gramps Web URL
Sync changes between desktop and web

Manual Import/Export

Alternatively, use manual sync:

Export from one platform (GEDCOM or Gramps backup)
Import to the other platform
Repeat when changes are made

Security Considerations

Access Control

User Registration: Control who can register
Role Assignment: Assign appropriate roles to users
Private Records: Mark sensitive information as private

Data Privacy

Self-Hosted: Your data stays on your server
HTTPS: Always use encrypted connections
Backup: Regularly back up your data
Living People: Configure privacy for living individuals

Authentication

Strong Passwords: Enforce strong password requirements
Email Verification: Enable email verification if SMTP is configured
Session Security: The secret key protects sessions

Troubleshooting Common Issues

Cannot Create User

Symptoms: Registration fails or user cannot be created.

Solutions:

Verify the registration URL includes the correct role parameter
Check that user database directory is writable
Review application logs for errors

Media Upload Failures

Symptoms: Cannot upload photos or documents.

Solutions:

Verify media directory is mounted and writable
Check file size limits
Ensure sufficient disk space

Search Not Working

Symptoms: Search returns no results.

Solutions:

Verify search index directory is mounted
Rebuild the search index from settings
Check disk space for index files

Sync Issues with Gramps Desktop

Symptoms: Changes don’t sync between platforms.

Solutions:

Verify the API connection is configured correctly
Check authentication credentials
Try manual export/import as alternative

Additional Resources

Conclusion

Deploying Gramps Web on Klutch.sh gives you a powerful, collaborative genealogy platform with full privacy control. The combination of Gramps Web’s comprehensive features and Klutch.sh’s deployment simplicity means you can share your family history online without complex infrastructure.

With interactive charts, mapping tools, and support for dozens of languages, Gramps Web transforms genealogical research into an engaging, shareable experience. Whether you’re documenting your ancestry for yourself or collaborating with family members worldwide, Gramps Web on Klutch.sh provides the foundation for preserving your family’s legacy.