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