Deploying Genealogy

Introduction

Genealogy is a free and open-source family tree PHP application for recording family members and their relationships. Built with Laravel 12 and modern PHP 8.4, this application provides a beautiful, responsive interface for documenting and exploring your family history.

The application features a clean design, intuitive user interface, and powerful features for managing genealogical data. It supports complex family relationships, media attachments, and detailed person profiles, making it suitable for both casual family historians and serious genealogists.

Key highlights of Genealogy:

• Modern Stack: Built with Laravel 12, PHP 8.4, and Livewire for a responsive experience
• Visual Family Tree: Interactive tree visualization of family relationships
• Person Profiles: Detailed profiles for each family member with photos and documents
• Relationship Tracking: Document marriages, children, parents, and other relationships
• Media Support: Attach photos and documents to individuals
• Timeline View: View life events chronologically
• Multi-User: Support for multiple users and teams
• GEDCOM Import/Export: Compatible with standard genealogy file format
• Responsive Design: Works on desktop and mobile devices
• Open Source: Licensed under MIT

This guide walks through deploying Genealogy on Klutch.sh using Docker, configuring persistent storage, and setting up the application for your family history project.

Why Deploy Genealogy on Klutch.sh

Deploying Genealogy on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Genealogy without complex orchestration. Push to GitHub, and your family tree application deploys automatically.

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

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

GitHub Integration: Connect your configuration repository directly from GitHub for automatic updates.

Scalable Resources: Allocate resources based on your needs as your family tree grows.

Custom Domains: Assign a custom domain for a family-branded genealogy portal.

Always-On Availability: Your family tree remains accessible 24/7 for relatives around the world.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Genealogy configuration
• Basic familiarity with Docker and containerization concepts
• A MySQL/MariaDB database (see MySQL deployment guide)
• (Optional) A custom domain for your Genealogy instance

Understanding Genealogy Architecture

Genealogy is built on a modern Laravel stack:

Laravel 12 Framework: The PHP framework provides routing, authentication, database abstraction, and more.

Livewire: Real-time, reactive components for a dynamic user experience without complex JavaScript.

MySQL/MariaDB: Database storage with support for Recursive Common Table Expressions for efficient tree queries.

Tailwind CSS: Modern utility-first CSS framework for responsive design.

Media Library: Handles photo and document storage and management.

Preparing Your Repository

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

Repository Structure

genealogy-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM php:8.4-apache

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    libzip-dev \
    zip \
    unzip \
    nodejs \
    npm \
    && rm -rf /var/lib/apt/lists/*

# Install PHP extensions
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd zip

# Enable Apache modules
RUN a2enmod rewrite

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www/html

# Clone the repository
RUN git clone https://github.com/MGeurts/genealogy.git .

# Install PHP dependencies
RUN composer install --no-dev --optimize-autoloader

# Install and build frontend assets
RUN npm ci && npm run build

# Set permissions
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html/storage \
    && chmod -R 755 /var/www/html/bootstrap/cache

# Configure Apache
RUN echo '<VirtualHost *:80>\n\
    DocumentRoot /var/www/html/public\n\
    <Directory /var/www/html/public>\n\
        AllowOverride All\n\
        Require all granted\n\
    </Directory>\n\
</VirtualHost>' > /etc/apache2/sites-available/000-default.conf

EXPOSE 80

CMD ["apache2-foreground"]

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Genealogy requires several environment variables:

Variable	Required	Default	Description
APP_NAME	No	Genealogy	Application name
APP_ENV	No	production	Application environment
APP_KEY	Yes	-	Laravel application key (base64)
APP_DEBUG	No	false	Debug mode
APP_URL	Yes	-	Full URL to your application
DB_CONNECTION	No	mysql	Database driver
DB_HOST	Yes	-	Database host
DB_PORT	No	3306	Database port
DB_DATABASE	Yes	genealogy	Database name
DB_USERNAME	Yes	-	Database username
DB_PASSWORD	Yes	-	Database password

Deploying Genealogy on Klutch.sh

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

Generate Application Key

Before deployment, generate a Laravel application key:

php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"

Save this key securely.

Set Up MySQL/MariaDB Database

Genealogy requires MySQL 8.0.1+ or MariaDB 10.2.2+ for Recursive Common Table Expression support. Deploy a database instance and create a database named genealogy.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Genealogy deployment configuration"
git remote add origin https://github.com/yourusername/genealogy-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 “genealogy” 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 Genealogy Dockerfile.

Configure HTTP Traffic

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

• Select HTTP as the traffic type
• Set the internal port to 80 (Apache’s default port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
APP_NAME	Your family name or project name
APP_ENV	production
APP_KEY	Your generated key (base64:…)
APP_DEBUG	false
APP_URL	https://your-app-name.klutch.sh
DB_HOST	Your MySQL/MariaDB host
DB_DATABASE	genealogy
DB_USERNAME	Your database username
DB_PASSWORD	Your database password

Attach Persistent Volumes

Add persistent storage for media files:

Mount Path	Recommended Size	Purpose
/var/www/html/storage/app	10 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 Genealogy container
• Provision an HTTPS certificate

Run Database Migrations

After deployment, run the database migrations to set up the tables:

php artisan migrate --force

Access Genealogy

Once deployment completes, access your Genealogy instance at https://your-app-name.klutch.sh. Register your first user account to become the administrator.

Initial Setup and Configuration

Creating Your First User

On first access:

1. Click Register
2. Fill in your details
3. The first registered user becomes an administrator

Creating Team (Optional)

If using teams:

1. Navigate to Teams
2. Create a new team for your family
3. Invite family members to collaborate

Adding Your First Person

Start building your family tree:

1. Click Add Person
2. Enter basic information:
   • First and last name
   • Birth date and place
   • Gender
   • Photo (optional)
3. Save the person

Building Your Family Tree

Adding Family Members

To add relatives:

1. Select an existing person
2. Choose to add:
   • Father
   • Mother
   • Spouse
   • Child
3. Fill in their details
4. The relationship is created automatically

Documenting Relationships

Record marriages and partnerships:

1. Navigate to a person
2. Click Add Partner
3. Select or create the partner
4. Add marriage details:
   • Date and place
   • Status (married, divorced, etc.)

Adding Events

Document life events:

Event Type	Example Data
Birth	Date, place, notes
Death	Date, place, cause
Marriage	Date, place, partner
Occupation	Job title, dates
Residence	Address, dates

Uploading Media

Add photos and documents:

1. Open a person’s profile
2. Click Add Media
3. Upload photos or documents
4. Add captions and dates

Viewing Your Family Tree

Tree View

Visualize relationships:

• Navigate up through ancestors
• Navigate down through descendants
• View siblings and spouses

Timeline View

See events chronologically:

• All events for a person
• Family-wide timeline
• Filter by event type

Reports

Generate reports:

• Ancestor reports
• Descendant reports
• Family group sheets

GEDCOM Import/Export

Importing Data

Import from other genealogy software:

1. Go to Import
2. Upload your GEDCOM file
3. Map fields if needed
4. Complete the import

Exporting Data

Export for backup or sharing:

1. Go to Export
2. Select GEDCOM format
3. Download the file

Production Best Practices

Security Recommendations

• Strong Passwords: Require strong passwords for all users
• APP_DEBUG: Always set to false in production
• Regular Backups: Back up database and media files
• Update Regularly: Keep Genealogy updated

Backup Strategy

Protect your family history:

1. Database Backups: Regular MySQL dumps
2. Media Backups: Back up storage/app directory
3. GEDCOM Export: Periodic GEDCOM exports

Troubleshooting Common Issues

Application Shows Error

Solutions:

• Check APP_KEY is set correctly
• Verify database connection
• Check storage permissions
• Review Laravel logs

Database Connection Failed

Solutions:

• Verify database credentials
• Check database host is accessible
• Ensure database exists
• Review MySQL version requirements

Media Not Loading

Solutions:

• Check storage permissions
• Verify volume is mounted
• Run php artisan storage:link

Additional Resources

• Genealogy GitHub Repository
• Laravel Documentation
• Klutch.sh MySQL Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Genealogy on Klutch.sh gives you a modern, feature-rich family tree application with automatic builds, persistent storage, and secure HTTPS access. The combination of Laravel’s robust framework and Klutch.sh’s deployment simplicity means you can focus on documenting your family history rather than managing infrastructure.

With visual tree navigation, detailed person profiles, and media support, Genealogy provides everything you need for comprehensive genealogical documentation. Whether you’re just starting to record your family history or digitizing decades of research, Genealogy on Klutch.sh delivers a reliable, always-available platform for preserving your heritage.