genealogy

Genealogy

About this project

Genealogy is a free and open-source family tree PHP application to record family members and their relationships, built with Laravel 13.

This TallStack application is built using:

• Laravel 13
• Laravel Jetstream 5 (featuring Teams)
• Livewire 4
• Alpine.js 3
• Tailwind CSS 4
• TallStackUI 4 (featuring Tabler Icons)
• Laravel Filament 5 (only Table Builder)

Logic concept

1. A person can have 1 biological father (1 person, based on father_id)

2. A person can have 1 biological mother (1 person, based on mother_id)

3. A person can have 1 set of parents, biological or not (1 couple of 2 people, based on parents_id)

4. A person can have 0 to many biological children (n people, based on father_id/mother_id)

5. A couple can have 0 to many (plus) children (based on parents_id as a couple or father_id/mother_id individually)

6. A person can have 0 to many partners (n people), being part of 0 to many couples (opposite or same biological sex)

7. A person can be part of a couple with the same partner multiple times (remarriage or reunite)

8. A person can have 0 to many siblings (n people) (based on parents_id as a couple or father_id/mother_id individually)

9. A couple can be married or not, still together or separated in the meantime

Requirements

• PHP 8.4 or later.
• Composer 2.
• Node.js 20.19+ or 22.12+ with npm.
• At least MySQL 8.0.1 or MariaDB 10.2.2 or an equivalent database, supporting Recursive Common Table Expressions.

HTTPS is required in production. HTTP is appropriate for local development only.

Docker

For local development with Docker, start with the Docker setup guide. Production images are published to the GitHub Container Registry on each release:

docker pull ghcr.io/mgeurts/genealogy:latest

Pin a deployment to a version tag, such as ghcr.io/mgeurts/genealogy:v1.2.3. See all available tags on the package page.

License

This project is open-sourced software licensed under the MIT license.

Demo

https://genealogy.kreaweb.be/

This demo has 2 family trees implemented, BRITISH ROYALS and KENNEDY.

E-mail	Password	Purpose
[email protected]	password	to access teams BRITISH ROYALS and KENNEDY as team owner
[email protected]	password	to access team BRITISH ROYALS as manager
[email protected]	password	to access team KENNEDY as editor
[email protected]	password	to access team BRITISH ROYALS as normal member
[email protected]	password	to access team KENNEDY as normal member
[email protected]	password	to access options reserved for the developer, like the user management and access to all persons in all teams

Roles & permissions

Teams & Users

Role	Model	Permissions
Team owner	personal team	update, invite members
	non-personal team	read, update, delete, invite members, transfer ownership
	new team	create
Team member	personal team	update, invite members
	non-personal team	accept membership, read, leave
	new team	create

Persons & Couples

Role	Model	Permissions
Administrator	person	create, read, update, delete
	couple	create, read, update, delete
Manager	person	create, read, update, delete
	couple	create, read, update, delete
Editor	person	create, read, update
	couple	create, read, update
Member	person	read
	couple	read

Features

• Light/Dark theme
• Fully responsive
• Multi-language, language setting saved in authenticated users profile
• Multi-timezone, timezone setting saved in authenticated users profile
• Multi-tenancy by Laravel Jetstream Teams, including Transfer Team Ownership
• Security through Laravel Jetstream Teams Roles & Permissions, 2FA & API can be enabled
• Offcanvas menu
• Multiple image upload with possibility of watermarking, photo carousel with navigation
• Multiple documents upload
• Event management & timeline overview

Special features

This application has a built-in Backup Manager:

• Backups can be initiated and managed manually.
• Daily backup and cleanup tasks are scheduled through Laravel's scheduler.
• An email is sent after each backup.

This application has a built-in Log Viewer, on demand showing :

• INFO : All scheduled backups
• DEBUG : All executed requests (off by default)
• DEBUG : All executed database queries (off by default)
• WARNING : All detected slow (> 500 ms) queries
• WARNING : All detected N+1 queries
• ERROR : All detected errors

Logging can be enabled or disabled by the developer in Offcanvas Menu Settings.

This application has a built-in User management & logging, available to the developer :

• User statistics by country of origin
• User statistics by year, month, week or day

The following activities are logged in the database:

• create, update, delete on persons (including Metadata) and couples
• create, update, delete on teams
• create, update, delete, invite, remove on users (Team members)

Activity loggings are available in Offcanvas Menu :

• Persons (with Couples) in People logbook
• Teams (with Users) in Team logbook

This application has a built-in Password Generator to help users build secure passwords.

GEDCOM Import and Export

At present, GEDCOM Import and Export functionality is under active development.
While still incomplete, initial Import and Export capabilities are already available.
The implementation of full GEDCOM (v7.x.x) Import and Export support represents a significantly larger effort than the development of the application itself.
To date, version 7 has not been fully implemented in any open-source php based project.
It is strongly recommended to create a backup of your database before testing any Import or Export features on production data.

Languages

• German (DE)
• English (EN)
• Spanish (ES)
• French (FR)
• Hindi (HI)
• Indonesian (ID)
• Dutch (NL)
• Portuguese (PT)
• Turkish (TR)
• Vietnamese (VI)
• Simplified Chinese (ZH_CN)

Translations can be added by submitting a Pull Request to the project.
Translation integrity can be checked by issuing the command:

php artisan translations:check --excludedDirectories=vendor

Instructions on how to add a language can be found in README-LANGUAGES.md.

The application does not support Right To Left (RTL) languages such as Arabic, Hebrew, Persian, Urdu, Pashto, Kurdish (Sorani), Uyghur, Syriac, Thaana, or North Korean.

Uploads

Instructions on how to configure file and image uploads can be found in README-UPLOADS.md.

Techniques

Both the ancestors and descendants family trees are build using Recursive Common Table Expressions (Recursive CTE). This prevents the N+1 query problem generating the recursive tree family elements and dramatically improves performance.

Local installation

The following instructions are for a new local installation. For Docker, see the Docker setup guide.

Create a new project folder and clone the repository:

git clone https://github.com/MGeurts/genealogy.git .

cp .env.example .env

Configure .env with your application URL and database connection. The defaults use MySQL and database-backed sessions, queues, and cache, so run the migrations before starting the application.

APP_URL=http://localhost:8000
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=genealogy
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

Install the PHP and JavaScript dependencies:

composer install --no-scripts
npm ci

Generate the application key and storage link:

php artisan key:generate
php artisan storage:link

Create the schema and seed the initial data:

php artisan migrate --seed

Run Composer’s post-install scripts after the database tables exist:

composer dump-autoload

Start the local development environment:

composer run dev

This starts the application server, queue listener, logs, and Vite development server. Open the local URL configured in APP_URL.

To build frontend assets without the development server:

npm run build

php artisan migrate:fresh --seed drops every table. Use it only to intentionally reset disposable local data, never for an existing or production database.

Production operations

Production deployments must use HTTPS with APP_ENV=production, APP_DEBUG=false, and an APP_URL that matches the public HTTPS URL. Store the database, uploaded files, and backups on persistent storage outside the deployment artifact.

Apply schema changes with the non-destructive migration command:

php artisan migrate --force

Run a persistent queue worker under your process supervisor:

php artisan queue:work --tries=3

Invoke Laravel’s scheduler every minute to run the configured backup cleanup and daily database backup tasks:

* * * * * cd /path/to/genealogy && php artisan schedule:run >> /dev/null 2>&1

Set BACKUP_DISK, BACKUP_MAIL_ADDRESS, and the mail settings in the production environment, then verify that backups can be restored before relying on them.

Updating

Update instructions can be found in README-UPDATE.md.

Reporting security issues

Instructions on how to report security issues can be found in SECURITY.md.

Testing

Testing is done using Pest.

Command:

php artisan test

or

./vendor/bin/pest

Production (or local development) data should be stored in a MySQL or MariaDB database configured in .env.

Testing data should be stored in a separate MySQL or MariaDB database configured in .env.testing to avoid interfering with the production or development data.

Command to create the testing MySQL database:

php artisan migrate --env=testing

Contributing

Feel free to submit Issues or Pull Requests, for bugs, suggestions or feature requests.

Documentation

The documentation is included in the applications help. Visit the demo project to read the documentation.

💖 Support This Project

Maintaining this project takes time and effort. If you find it useful, consider supporting me:

• 
• 
• 

Your support helps me improve and maintain Genealogy and other open-source tools. Every bit is appreciated. Thank you! 🙏

Impressum

Design & Development (2024)

This Laravel application is designed and developed by kreaweb.be.