Deploying webtrees

Introduction

webtrees is the leading online collaborative genealogy application, providing a comprehensive platform for building, viewing, and sharing your family tree. Used by genealogists worldwide, webtrees offers professional-grade features while remaining completely free and open source.

Built with PHP, webtrees supports the GEDCOM standard (the universal file format for genealogical data), allowing you to import existing family trees from other applications and export your work for backup or sharing. The web-based interface makes it accessible from any device while keeping your sensitive family data under your control.

Key highlights of webtrees:

GEDCOM Support: Import and export standard GEDCOM files
Interactive Charts: Pedigree charts, fan charts, family trees, and more
Powerful Search: Find ancestors across multiple generations
Multi-Tree Support: Manage multiple family trees in one installation
Multi-User: Collaborate with family members with granular permissions
Media Management: Attach photos, documents, and audio to records
Theming: Multiple themes and customization options
Reports: Generate various genealogical reports
Privacy Controls: Control who can see what information
Localization: Available in dozens of languages
Extensible: Plugin system for additional features
Open Source: Active community development since 2010

This guide walks through deploying webtrees on Klutch.sh using Docker, configuring the database, and setting up your genealogy platform.

Why Deploy webtrees on Klutch.sh

Deploying webtrees on Klutch.sh provides several advantages for genealogy research:

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

Persistent Storage: Attach persistent volumes for your database, media files, and GEDCOM data. Your family history survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to sensitive family information.

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

Family Collaboration: Share your tree with relatives around the world with always-on availability.

Scalable Resources: Allocate CPU and memory based on your tree size and expected users.

Custom Domains: Assign a custom domain for your family history site.

Prerequisites

Before deploying webtrees on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your webtrees configuration
Basic familiarity with Docker and containerization concepts
A MySQL/MariaDB database (or plan to deploy one)
(Optional) GEDCOM files from existing genealogy software
(Optional) A custom domain for your webtrees instance

Preparing Your Repository

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

Repository Structure

webtrees-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/nathanvaughn/webtrees:latest

# Set environment variables
ENV PRETTY_URLS=true
ENV HTTPS=true
ENV HTTPS_REDIRECT=false
ENV LANG=en_US.UTF-8

# Database configuration
ENV DB_TYPE=mysql
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=${DB_PORT:-3306}
ENV DB_NAME=${DB_NAME}
ENV DB_USER=${DB_USER}
ENV DB_PASS=${DB_PASS}
ENV DB_PREFIX=wt_

# webtrees configuration
ENV BASE_URL=${BASE_URL}
ENV WT_NAME=${WT_NAME:-Family Tree}
ENV WT_EMAIL=${WT_EMAIL}

# Expose the web interface port
EXPOSE 80

Alternative: Using SQLite

For simpler deployments without external database:

FROM ghcr.io/nathanvaughn/webtrees:latest

# Set environment variables
ENV PRETTY_URLS=true
ENV HTTPS=true
ENV HTTPS_REDIRECT=false
ENV LANG=en_US.UTF-8

# SQLite configuration
ENV DB_TYPE=sqlite

# webtrees configuration
ENV BASE_URL=${BASE_URL}
ENV WT_NAME=${WT_NAME:-Family Tree}
ENV WT_EMAIL=${WT_EMAIL}

EXPOSE 80

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
`BASE_URL`	Yes	-	Full URL of your webtrees instance
`DB_TYPE`	No	mysql	Database type (mysql, pgsql, sqlite)
`DB_HOST`	Conditional	-	Database host (required for mysql/pgsql)
`DB_NAME`	Conditional	-	Database name
`DB_USER`	Conditional	-	Database username
`DB_PASS`	Conditional	-	Database password
`WT_NAME`	No	webtrees	Default tree name
`WT_EMAIL`	No	-	Administrator email
`PRETTY_URLS`	No	true	Enable pretty URLs
`HTTPS`	No	false	Set to true when behind HTTPS proxy

Deploying webtrees on Klutch.sh

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

Set Up MySQL/MariaDB Database

webtrees works best with MySQL or MariaDB. You can either:

Use a managed database service
Deploy MariaDB as a separate app on Klutch.sh

Ensure you have your database credentials ready.

Push Your Repository to GitHub

Initialize your repository and push to GitHub. Ensure your Dockerfile is in the root of your repository.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “webtrees” 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 webtrees Dockerfile.

Configure HTTP Traffic

webtrees serves its web interface over HTTP. In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
`BASE_URL`	`https://your-app-name.klutch.sh`
`DB_HOST`	Your database host
`DB_NAME`	Your database name
`DB_USER`	Your database username
`DB_PASS`	Your database password
`HTTPS`	`true`
`WT_EMAIL`	Your email address

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/www/webtrees/data`	10 GB	GEDCOM files, cache, and configuration
`/var/www/webtrees/media`	20 GB	Photos and documents

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 webtrees container
Provision an HTTPS certificate

Complete Setup Wizard

Access your webtrees instance at https://your-app-name.klutch.sh and complete the initial setup wizard to create your administrator account.

Initial Configuration

First-Time Setup

When you first access webtrees:

The setup wizard will verify database connectivity
Create your administrator account
Set up your first family tree
Configure basic settings

Creating Your First Tree

Start your family history:

Navigate to Control Panel > Manage family trees
Click Create a new family tree
Enter a name and description
Choose privacy settings
Create the tree

Importing GEDCOM Data

If you have existing genealogy data:

Go to Control Panel > Manage family trees
Select your tree
Click Import a GEDCOM file
Upload your GEDCOM file
Configure import settings
Start the import

webtrees supports GEDCOM from most genealogy applications including:

Ancestry
FamilySearch
Gramps
Legacy Family Tree
RootsMagic
Family Tree Maker

Managing Your Family Tree

Adding Individuals

Add family members:

Navigate to your tree
Click Add > Add an individual
Enter name, dates, and places
Add relationships to existing individuals
Save the record

Adding Media

Attach photos and documents:

Navigate to the individual’s record
Click on Media tab
Upload photos, documents, or certificates
Add descriptions and dates
Link to relevant individuals

Privacy Settings

Control who sees what:

Access Levels:

Visitor: Limited access to non-living individuals
Member: Can view most records
Editor: Can edit records
Manager: Full access to tree
Administrator: System-wide access

Privacy Options:

Hide living individuals from visitors
Restrict specific facts or notes
Control media visibility

User Management

Adding Users

Invite family members:

Go to Control Panel > Users
Click Add a user
Enter email and user details
Assign role and tree access
Send invitation

User Roles

webtrees has granular permissions:

Role	Capabilities
Visitor	View public data only
Member	View most records, can’t edit
Editor	Add and edit records
Moderator	Approve pending changes
Manager	Full tree management
Administrator	System configuration

Customization

Themes

Change the appearance:

Go to Control Panel > Website preferences
Select from available themes
Configure theme-specific options

Modules

Enable additional features:

Go to Control Panel > Modules
Enable/disable features per tree
Configure module settings

Charts and Reports

webtrees includes numerous charts:

Pedigree charts
Fan charts
Descendancy charts
Relationship charts
Family book
Timeline

Production Best Practices

Security Recommendations

Strong Passwords: Enforce strong passwords for all users
HTTPS Only: Always use HTTPS (Klutch.sh handles this)
Regular Backups: Export GEDCOM regularly
Privacy Settings: Configure appropriate privacy defaults
User Verification: Verify new user identities

Performance

Database: Use MySQL/MariaDB for better performance
Media Optimization: Resize large images before uploading
Resource Allocation: Increase resources for large trees

Backup Strategy

GEDCOM Export: Regularly export to GEDCOM format
Database Backup: Back up the database
Media Backup: Back up the media volume
Test Restores: Periodically test restoring from backups

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container crashes on startup.

Solutions:

Verify database connection settings
Check that BASE_URL is set correctly
Review logs for specific errors

GEDCOM Import Fails

Symptoms: Import stops or shows errors.

Solutions:

Check GEDCOM file validity
Increase PHP memory limits if needed
Import in smaller chunks for very large files

Media Not Displaying

Symptoms: Photos show broken links.

Solutions:

Verify media volume is mounted correctly
Check file permissions
Confirm BASE_URL includes HTTPS

Performance Issues

Symptoms: Slow page loads or timeouts.

Solutions:

Increase allocated resources
Optimize database queries
Consider using MySQL instead of SQLite

Additional Resources

Conclusion

Deploying webtrees on Klutch.sh gives you a professional-grade genealogy platform with automatic builds, persistent storage, and secure HTTPS access. The combination of webtrees’ comprehensive features and Klutch.sh’s deployment simplicity means you can focus on researching your family history rather than managing infrastructure.

Whether you’re just starting to document your family tree or managing generations of research, webtrees on Klutch.sh provides a reliable, secure platform for preserving and sharing your family history with relatives around the world.