1 2 3[](https://github.com/fisharebest/webtrees/actions/workflows/phpunit.yaml) 4[](https://coveralls.io/github/fisharebest/webtrees?branch=main) 5[](https://weblate.iet.open.ac.uk/projects/webtrees/webtrees/) 6[](https://insight.symfony.com/projects/78a5ba19-7ddf-4a58-8262-1c8a149f38de) 7[](https://scrutinizer-ci.com/g/fisharebest/webtrees/?branch=main) 8[](https://codeclimate.com/github/fisharebest/webtrees) 9[](https://github.styleci.io/repos/11836349?branch=main) 10# webtrees - online collaborative genealogy 11 12## Contents 13 14* [License](#license) 15* [Coding styles and standards](#coding-styles-and-standards) 16* [Introduction](#introduction) 17* [System requirements](#system-requirements) 18* [Internet browser compatibility](#internet-browser-compatibility) 19* [Installation](#installation) 20* [Upgrading](#upgrading) 21* [Building and developing](#building-and-developing) 22* [Gedcom (family tree) files](#gedcom-family-tree-files) 23* [Security](#security) 24* [Backup](#backup) 25 26 27## License 28 29* **webtrees: online genealogy** 30* Copyright 2021 webtrees development team 31 32This program is free software: you can redistribute it and/or modify 33it under the terms of the GNU General Public License as published by 34the Free Software Foundation, either version 3 of the License, or 35(at your option) any later version. 36 37This program is distributed in the hope that it will be useful, 38but WITHOUT ANY WARRANTY; without even the implied warranty of 39MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 40GNU General Public License for more details. 41 42You should have received a copy of the GNU General Public License 43along with this program. If not, see <https://www.gnu.org/licenses/>. 44 45## Coding styles and standards 46 47webtrees follows the [PHP Standards Recommendations](https://www.php-fig.org/psr). 48 49* [PSR-1](https://www.php-fig.org/psr/psr-1) - Basic Coding Standard 50* [PSR-2](https://www.php-fig.org/psr/psr-2) - Coding Style Guide 51* [PSR-4](https://www.php-fig.org/psr/psr-4) - Autoloading Stardard 52* [PSR-6](https://www.php-fig.org/psr/psr-6) - Cache 53* [PSR-7](https://www.php-fig.org/psr/psr-7) - HTTP Message Interface 54* [PSR-11](https://www.php-fig.org/psr/psr-11) - Container Interface 55* [PSR-12](https://www.php-fig.org/psr/psr-12) - Extended Coding Style Guide 56* [PSR-15](https://www.php-fig.org/psr/psr-15) - HTTP Handlers 57* [PSR-17](https://www.php-fig.org/psr/psr-17) - HTTP Factories 58 59We do not currently use [PSR-3 (logging)](https://www.php-fig.org/psr/psr-3) - but we plan to do so in the future. 60 61For JavaScript, we use [semistandard](https://github.com/standard/semistandard). 62 63## Introduction 64 65**webtrees** is the web's leading online collaborative genealogy application. 66 67* It works from standard GEDCOM files, and is therefore compatible with every 68major desktop application. 69* It aims to to be efficient and effective by using the right combination of 70third-party tools, design techniques and open standards. 71 72**webtrees** allows you to view and edit your genealogy on your website. It has 73full editing capabilities, full privacy functions, and supports imedia such as 74photos and document images. As an online program, it fosters extended family 75participation and good ancestral recording habits, as it simplifies the process 76of collaborating with others working on your family lines. Your latest information 77is always on your web site and available for others to see, defined by viewing 78rules you set. For more information and to see working demos, visit 79[webtrees.net](https://webtrees.net/). 80 81**webtrees** is Open Source software that has been produced by people from many 82countries freely donating their time and talents to the project. All service, 83support, and future development is dependent on the time developers are willing 84to donate to the project, often at the expense of work, recreation, and family. 85Beyond the few donations received from users, developers receive no compensation 86for the time they spend working on the project. There is also no outside source 87of revenue to support the project. Please consider these circumstances when 88making support requests and consider volunteering your own time and skills to make 89the project even stronger and better. 90 91 92## System requirements 93 94To install **webtrees**, you need: 95 96* A webserver. Apache, NGINX and IIS are the most common types. To use “Pretty URLs”, you will need to configure URL rewriting" 97* 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. 98* Approximately 100MB of disk space for the application files, plus whatever is 99 needed for your media files, GEDCOM files and database. 100* PHP 7.1 - 7.4. Servers with PHP 5.3 - 7.0 can use **webtrees** 1.7. 101 * PHP should be configured to allow sufficient server resources (memory and 102 execution time) for the size of your system. Typical requirements are: 103 * Small systems (500 individuals): 16–32 MB, 10–20 seconds 104 * Medium systems (5,000 individuals): 32–64 MB, 20–40 seconds 105 * Large systems (50,000 individuals): 64–128 MB, 40–80 seconds 106 107## Browser compatibility 108 109 **webtrees** is tested on recent versions of popular browsers such as Edge, Firefox, 110 Chrome, and Safari. Support for other browsers and older versions is on a case-by-case basis. 111 112## Installation 113 1141. Download the .ZIP file for latest stable version from [github.com](https://github.com/fisharebest/webtrees/releases/latest) 1152. Unzip the files and then upload them to an empty folder on your web server. 1163. Open your web browser and type the URL for your **webtrees** site (for example, 117 ``https://www.yourserver.com/webtrees`` into the address bar. 1184. The **webtrees** setup wizard will start automatically. 119 120Your first task will be to create a family tree. 121 122If you have a GEDCOM file, you can import it into the tree. If not, just start 123entering your family tree. 124 125There are lots of configuration options. You'll probably want to review the 126privacy settings first. Don't worry too much about all the other options - the 127defaults are good for most people. If you get stuck, you can get friendly help 128and advice from the [help](https://webtrees.net/forums) forum. 129 130 131## Upgrading 132 133Upgrading **webtrees** is quick and easy. It is strongly recommended that you 134upgrade your installation whenever a new version is made available. Even minor 135**webtrees** version updates usually contain a significant number of bug fixes 136as well as interface improvements and program enhancements. 137 138* **Automatic upgrade** 139 140 **webtrees** has an automatic upgrade facility. An administrator upon logging in 141will receive notification when a new version is available and an option to start 142the automatic upgrade. If for some reason the automatic upgrade should fail 143then a manual upgrade should be performed. 144 145* **Manual upgrade** 146 147 1. Now would be a good time to make a [backup](#backup). 148 2. Download the latest version of **webtrees** available from 149 [webtrees.net](https://webtrees.net/) 150 3. While you are in the middle of uploading the new files, 151 a visitor to your site would encounter a mixture of new and old files. This 152 could cause unpredictable behavior or errors. To prevent this, create the 153 file **data/offline.txt**. While this file exists, visitors will see a 154 “site unavailable - come back later” message. 155 4. Unzip the .ZIP file, and upload the files to your web server, overwriting the existing files. 156 5. Delete the file **data/offline.txt** 157 158 159### Note for Macintosh users 160 161Step 4 assumes you are using a copy tool that **merges** directories rather than 162replaces them. (**Merge** is standard behavior on Windows and Linux.) If you use 163the Macintosh Finder or other similar tool to perform step 3, it will **replace** 164your configuration, media and other directories with the empty/default ones from 165the installation. This would be very bad (but you did take a backup in step 1, 166didn't you!). Further details and recommendations for suitable tools can be found 167by searching [google.com](https://google.com). 168 169 170## Building and developing 171 172If you want to build webtrees from source, or modify the code, you'll need to install 173a couple of tools first. 174 175You will need [composer](https://getcomposer.org/) to install the PHP dependencies. 176Then run this command:: 177 178* php composer.phar install 179 180You will need [npm](https://www.npmjs.com/get-npm) to install the Javascript dependencies. 181Then run the commands: 182 183* npm install 184* npm run production 185 186You will need to re-run the second of these any time you modify the file `webtrees.js`. 187 188## Gedcom (family tree) files 189 190When you import a family tree (GEDCOM) file in **webtrees** the 191data from the file is transferred to the database tables. The file itself 192remains in the **webtrees/data** folder and is no longer used or required 193by **webtrees**. Any subsequent editing of the **webtrees** data 194will not change this file 195 196When or if you change your genealogy data outside of **webtrees**, it is not 197necessary to delete your GEDCOM file or database from **webtrees** and start 198over. Follow these steps to update a GEDCOM that has already been imported: 199 200* Go to ``Control panel`` -> ``Manage family trees`` On the line relating to this particular family tree (GEDCOM) 201 file (or a new one) select IMPORT. 202* Take careful note of the media items option (_“If you have created media objects 203 in **webtrees**, and have edited your data off-line using software that 204 deletes media objects, then tick this box to merge the current media objects 205 with the new GEDCOM.”_) In most cases you should leave this box **UNCHECKED**. 206* Click “SAVE”. **webtrees** will validate the GEDCOM again before importing. 207 During this process, **webtrees** copies your entire family tree (GEDCOM file) 208 to a 'chunk' table within your database. Depending on the coding of your file, 209 its file size and the capabilities of your server and the supporting software, 210 this may take some time. **No progress bar will show while the data is being 211 copied** and should you navigate away from this page, the process is suspended. 212 It will start again when you return to the Family Tree management page. 213 214 215### Gedcom file Formats 216 217Every Family History program has its own method of creating GEDCOM files, and 218differing output format options to select from. **webtrees'** import routines 219can read many different formats, but not necessarily all. If your software has 220a “UTF8” option you should always use that. However, **webtrees** has been 221tested with these alternative formats: 222 223* ANSI 224 * imports OK, but is slow due to the translation into UTF8 as part 225 of the import process. 226* MAC 227 * imports OK, but is slow due to the translation into UTF8 as part 228 of the import process. 229* DOS 230 * imports OK, but is slow due to the translation into UTF8 as part 231 of the import process. 232* ANSEL 233 * currently will not import. Gives warning *Error: cannot convert 234 GEDCOM file from ANSEL encoding to UTF-8 encoding*. Later releases 235 of **webtrees** may include the facility to translate from ANSEL to UTF8, 236 but for now a standalone utility [is available here](https://dev.webtrees.net/ansel/) 237 and should be used to convert the format to UTF-8 prior to importing. 238 239 240## Security 241 242**Security** in _webtrees_ means ensuring your site is safe from unwanted 243intrusions, hacking, or access to data and configuration files. The developers 244of _webtrees_ regard security as an extremely important part of its development 245and have made every attempt to ensure your data is safe. 246 247The area most at risk of intrusion would be the **/data** folder that contains your 248config.ini.php file, and various temporary files. If you are concerned there 249may be a risk there is a very simple test you can do: try to fetch the file 250config.ini.php by typing **``url_to_your_server/data/config.ini.php``** in your web 251browser. 252 253The most likely result is an “access denied” message like this: 254 255 Forbidden 256 257 You don't have permission to access /data/config.ini.php on this server. 258 259This indicates that the protection built into **webtrees** is working, and no 260further action is required. 261 262In the unlikely event you do fetch the file (you will just see a semicolon), 263then that protection is not working on your site and you should take some further 264action. 265 266If your server runs PHP in CGI mode, then change the permission of the **/data** 267folder to 700 instead of 777. This will block access to the httpd process, 268while still allowing access to PHP scripts. 269 270This will work for perhaps 99% of all users. Only the remaining 1% should consider 271the most complex solution, moving the **/data** folder out of accessible web 272space. (**_Note:_** In many shared hosting environments this is not an option anyway.) 273 274If you do find it necessary, following is an example of the process required: 275 276If your home folder is something like **/home/username**, 277and the root folder for your web site is **/home/username/public_html**, 278and you have installed **webtrees** in the **public_html/webtrees** folder, 279then you would create a new **data** folder in your home folder at the same 280level as your public_html folder, such as **/home/username/private/data**, 281and place your GEDCOM (family tree) file there. 282 283Then change the **Data folder** setting on the ``Control panel`` -> 284``Website`` -> ``Website preferences`` page from the default **data/** to the new 285location **/home/username/private/data** 286 287You will have **two** data directories: 288 289* [path to webtrees]/data - just needs to contain config.ini.php 290* /home/username/private/data - contains everything else 291 292 293## Backup 294 295Backups are good. Whatever problem you have, it can always be fixed from a good 296backup. 297 298To make a backup of **webtrees**, you need to make a copy of the following 299 3001. The files in the *webtrees/data* folder. 3012. The files in the *webtrees/media* folder. 3023. The tables in the database. Freely available tools such as 303 [phpMyAdmin](https://www.phpmyadmin.net) allow you to do this in one click. 304 305Remember that most web hosting services do NOT backup your data, and this is 306your responsibility. 307
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}