Repository files navigation

• License
• Coding styles and standards
• Introduction
• System requirements
• Internet browser compatibility
• Installation
• Upgrading
• Building and developing
• Gedcom (family tree) files
• Security
• Backup
• Restore from Backup

• webtrees: online genealogy
• Copyright 2022 webtrees development team

This program is free software: you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with this program. If not, seehttps://www.gnu.org/licenses/.

webtrees follows thePHP Standards Recommendations.

• PSR-1 - Basic Coding Standard
• PSR-2 - Coding Style Guide
• PSR-4 - Autoloading Standard
• PSR-6 - Cache
• PSR-7 - HTTP Message Interface
• PSR-11 - Container Interface
• PSR-12 - Extended Coding Style Guide
• PSR-15 - HTTP Handlers
• PSR-17 - HTTP Factories

We do not currently usePSR-3 (logging) - but we plan to do so in the future.

For JavaScript, we usesemistandard.

webtrees is the web's leading online collaborative genealogy application.

• It works from standard GEDCOM files, and is therefore compatible with everymajor desktop application.
• It aims to to be efficient and effective by using the right combination ofthird-party tools, design techniques and open standards.

webtrees allows you to view and edit your genealogy on your website. It hasfull editing capabilities, full privacy functions, and supports imedia such asphotos and document images. As an online program, it fosters extended familyparticipation and good ancestral recording habits, as it simplifies the processof collaborating with others working on your family lines. Your latest informationis always on your web site and available for others to see, defined by viewingrules you set. For more information and to see working demos, visitwebtrees.net.

webtrees is Open Source software that has been produced by people from manycountries freely donating their time and talents to the project. All service,support, and future development is dependent on the time developers are willingto donate to the project, often at the expense of work, recreation, and family.Beyond the few donations received from users, developers receive no compensationfor the time they spend working on the project. There is also no outside sourceof revenue to support the project. Please consider these circumstances whenmaking support requests and consider volunteering your own time and skills to makethe project even stronger and better.

To installwebtrees, you need:

• A webserver. Apache, NGINX and IIS are the most common types. To use “Pretty URLs”, you will need to configure URL rewriting"
• A database. MySQL is recommended, although PostgreSQL, SQL-Server and SQLite can be used. Some features rely on MySQL for collation. Other database might not sort names according to local rules.webtrees uses a prefix for its table names, so you can install several instances of webtrees in the same database.
• Approximately 100MB of disk space for the application files, plus whatever isneeded for your media files, GEDCOM files and database.
• PHP 7.1 - 7.4. Servers with PHP 5.3 - 7.0 can usewebtrees 1.7.
  • PHP should be configured to allow sufficient server resources (memory andexecution time) for the size of your system. Typical requirements are:
    • Small systems (500 individuals): 16–32 MB, 10–20 seconds
    • Medium systems (5,000 individuals): 32–64 MB, 20–40 seconds
    • Large systems (50,000 individuals): 64–128 MB, 40–80 seconds

webtrees is tested on recent versions of popular browsers such as Edge, Firefox,Chrome, and Safari. Support for other browsers and older versions is on a case-by-case basis.

1. Download the .ZIP file for latest stable version fromgithub.com.
2. Unzip the files and then upload them to an empty folder on your web server.
3. Open your web browser and type the URL for yourwebtrees site (for example,https://www.yourserver.com/webtrees into the address bar.
4. Thewebtrees setup wizard will start automatically.

Your first task will be to create a family tree.

If you have a GEDCOM file, you can import it into the tree. If not, just startentering your family tree.

There are lots of configuration options. You'll probably want to review theprivacy settings first. Don't worry too much about all the other options - thedefaults are good for most people. If you get stuck, you can get friendly helpand advice from thehelp forum.

Upgradingwebtrees is quick and easy. It is strongly recommended that youupgrade your installation whenever a new version is made available. Even minorwebtrees version updates usually contain a significant number of bug fixesas well as interface improvements and program enhancements.

• Automatic upgrade

  webtrees has an automatic upgrade facility. An administrator upon logging inwill receive notification when a new version is available and an option to startthe automatic upgrade. If for some reason the automatic upgrade should failthen a manual upgrade should be performed.

• Manual upgrade

  1. Now would be a good time to make abackup.
  2. Download the latest version ofwebtrees available fromwebtrees.net
  3. While you are in the middle of uploading the new files,a visitor to your site would encounter a mixture of new and old files. Thiscould cause unpredictable behavior or errors. To prevent this, create thefiledata/offline.txt. While this file exists, visitors will see a“site unavailable - come back later” message.
  4. Unzip the .ZIP file, and upload the files to your web server, overwriting the existing files.
  5. Delete the filedata/offline.txt.

Step 4 assumes you are using a copy tool thatmerges directories rather thanreplaces them. (Merge is standard behavior on Windows and Linux.) If you usethe Macintosh Finder or other similar tool to perform step 3, it willreplaceyour configuration, media and other directories with the empty/default ones fromthe installation. This would be very bad (but you did take a backup in step 1,didn't you!). Further details and recommendations for suitable tools can be foundby searchinggoogle.com.

If you want to build webtrees from source, or modify the code, you'll need to installa couple of tools first.

You will needcomposer to install the PHP dependencies.Then run this command::

• php composer.phar install

You will neednpm to install the Javascript dependencies.Then run the commands:

• npm install
• npm run production

You will need to re-run the second of these any time you modify the filewebtrees.js.

When you import a family tree (GEDCOM) file inwebtrees thedata from the file is transferred to the database tables. The file itselfremains in thewebtrees/data folder and is no longer used or requiredbywebtrees. Any subsequent editing of thewebtrees datawill not change this file

When or if you change your genealogy data outside ofwebtrees, it is notnecessary to delete your GEDCOM file or database fromwebtrees and startover. Follow these steps to update a GEDCOM that has already been imported:

• Go toControl panel ->Manage family trees On the line relating to this particular family tree (GEDCOM)file (or a new one) select IMPORT.
• Take careful note of the media items option (“If you have created media objectsinwebtrees, and have edited your data off-line using software thatdeletes media objects, then tick this box to merge the current media objectswith the new GEDCOM.”) In most cases you should leave this boxUNCHECKED.
• Click “SAVE”.webtrees will validate the GEDCOM again before importing.During this process,webtrees copies your entire family tree (GEDCOM file)to a 'chunk' table within your database. Depending on the coding of your file,its file size and the capabilities of your server and the supporting software,this may take some time.No progress bar will show while the data is beingcopied and should you navigate away from this page, the process is suspended.It will start again when you return to the Family Tree management page.

Security inwebtrees means ensuring your site is safe from unwantedintrusions, hacking, or access to data and configuration files. The developersofwebtrees regard security as an extremely important part of its developmentand have made every attempt to ensure your data is safe.

The area most at risk of intrusion would be the/data folder that contains yourconfig.ini.php file, and various temporary files. If you are concerned theremay be a risk there is a very simple test you can do: try to fetch the fileconfig.ini.php by typingurl_to_your_server/data/config.ini.php in your webbrowser.

The most likely result is an “access denied” message like this:

ForbiddenYou don't have permission to access /data/config.ini.php on this server.

This indicates that the protection built intowebtrees is working, and nofurther action is required.

In the unlikely event you do fetch the file (you will just see a semicolon),then that protection is not working on your site and you should take some furtheraction.

If your server runs PHP in CGI mode, then change the permission of the/datafolder to 700 instead of 777. This will block access to the httpd process,while still allowing access to PHP scripts.

This will work for perhaps 99% of all users. Only the remaining 1% should considerthe most complex solution, moving the/data folder out of accessible webspace. (Note: In many shared hosting environments this is not an option anyway.)

If you do find it necessary, following is an example of the process required:

If your home folder is something like/home/username,and the root folder for your web site is/home/username/public_html,and you have installedwebtrees in thepublic_html/webtrees folder,then you would create a newdata folder in your home folder at the samelevel as your public_html folder, such as/home/username/private/data,and place your GEDCOM (family tree) file there.

Then change theData folder setting on theControl panel ->Website ->Website preferences page from the defaultdata/ to the newlocation/home/username/private/data

You will havetwo data directories:

• [path to webtrees]/data - just needs to contain config.ini.php
• /home/username/private/data - contains everything else

Backups are good. Whatever problem you have, it can always be fixed from a goodbackup.

To make a backup ofwebtrees, you need to make a copy of the following

1. The files in thewebtrees/data folder.

2. The tables in the database. Freely available tools such asphpMyAdmin allow you to do this in one click. Alternatively, You can also make a backup running a mysqldump command (just replace the words[localhost],[username],[password] and[databasename] with your own):

   mysqldump --host=[localhost] -u [username] -p[password] --databases [databasename] > dump_file.sql

   Note that '-p[password]' goes together with no space in between.

Remember that most web hosting services do NOT backup your data, and this isyour responsibility.

To restore a backup on a new server:

1. Follow the steps inInstallation to get a clean new installation.

2. Replace thedata folder with backup copy.

3. Restore your mysql database using phpmyadmin or running the following command line on your database server using your mysqldumpfile (just replace the words[username],[password] and[databasename] with your own):

   mysql -u [username] -p[password] [database_name] < [dump_file.sql]

4. Confirm the filedata/config.ini.php contains to correct information to connect to the database and update it if needed.