1[](https://packagist.org/packages/fisharebest/webtrees) 2[](https://packagist.org/packages/fisharebest/webtrees) 3[](https://packagist.org/packages/fisharebest/webtrees) 4[](https://travis-ci.org/fisharebest/webtrees) 5[](https://coveralls.io/github/fisharebest/webtrees?branch=master) 6[](https://translate.webtrees.net/engage/webtrees/?utm_source=widget) 7[](https://insight.sensiolabs.com/projects/78a5ba19-7ddf-4a58-8262-1c8a149f38de) 8[](https://scrutinizer-ci.com/g/fisharebest/webtrees/?branch=master) 9[](https://codeclimate.com/github/fisharebest/webtrees) 10[](https://github.styleci.io/repos/11836349) 11 12# webtrees 13 14The project’s website is [www.webtrees.net](https://www.webtrees.net). 15Further documentation is available at [wiki.webtrees.net](https://wiki.webtrees.net) and [webtrees.github.io](https://webtrees.github.io). 16 17## Contents 18 19* [License](#license) 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 (C) 2019 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 50### Introduction 51 52**webtrees** is the web's leading online collaborative genealogy application. 53 54* It works from standard GEDCOM files, and is therefore compatible with every 55major desktop application. 56* It aims to to be efficient and effective by using the right combination of 57third-party tools, design techniques and open standards. 58 59**webtrees** allows you to view and edit your genealogy on your website. It has 60full editing capabilities, full privacy functions, and supports imedia such as 61photos and document images. As an online program, it fosters extended family 62participation and good ancestral recording habits, as it simplifies the process 63of collaborating with others working on your family lines. Your latest information 64is always on your web site and available for others to see, defined by viewing 65rules you set. For more information and to see working demos, visit 66[webtrees.net](https://webtrees.net/). 67 68**webtrees** is Open Source software that has been produced by people from many 69countries freely donating their time and talents to the project. All service, 70support, and future development is dependent on the time developers are willing 71to donate to the project, often at the expense of work, recreation, and family. 72Beyond the few donations received from users, developers receive no compensation 73for the time they spend working on the project. There is also no outside source 74of revenue to support the project. Please consider these circumstances when 75making support requests and consider volunteering your own time and skills to make 76the project even stronger and better. 77 78 79### System requirements 80 81To install **webtrees**, you need: 82 83* A webserver. Apache, NGINX and IIS are the most common types. There are no 84 requirements to use a specific type or version. 85* Approximately 65MB of disk space for the application files, plus whatever is 86 needed for your media files, GEDCOM files and database. 87* PHP 7.0 or later. Servers with PHP 5.3 - 5.6 should use **webtrees** 1.7. 88 Servers with PHP 5.2 should use **webtrees** 1.4. 89 * PHP should be configured with the following libraries: 90 * PDO and pdo_mysql to enable access to MySQL. These are enabled by default 91 on most hosts. See [http://php.net/pdo](http://php.net/pdo), 92 * php\_gd(2) for images 93 * PHP_XML for reports. 94 * PHP should be configured to allow sufficient server resources (memory and 95 execution time) for the size of your system. Typical requirements are: 96 * Small systems (500 individuals): 16–32 MB, 10–20 seconds 97 * Medium systems (5,000 individuals): 32–64 MB, 20–40 seconds 98 * Large systems (50,000 individuals): 64–128 MB, 40–80 seconds 99* MySQL or MariaDB. Note that **webtrees** can share a single database 100 with other applications, by choosing a unique table prefix during setup. 101 If the number of databases is not restricted, you can set up a database purely 102 for use by **webtrees** and create a separate user and password for only 103 your genealogy. 104 105 106 ### Internet browser compatibility 107 108 **webtrees** supports the use of most current browsers such as Edge, Firefox, 109 Chrome, and Safari. We will do our best to support the current versions of others 110 such as Opera and Internet Explorer, however note that versions of Internet Explorer 111 prior to IE11 do not work with **webtrees**. We strongly recommend anyone using an 112 obsolete browser to upgrade as soon as possible. We are also aware that Internet 113 Explorer provides poor RTL language support generally, so cannot recommend it for 114 sites requiring RTL languages. 115* To view sites that contain both left-to-right and right-to-left text (e.g. 116 English data on Hebrew pages), you will need to use a browser that provides 117 support for the HTML5 **dir="auto"** attribute. At present, neither Edge 118 nor Internet Explorer support this. 119* HTML Frames. Note that **webtrees** uses cookies to track login sessions. 120 Internet Explorer users should review 121 ``Settings`` / ``Internet Options`` / ``Privacy`` / ``Advanced`` for more details. 122 123 124### Installation 125 126Once the system requirements are met, perform the following steps 127 1281. Download the latest stable version from [webtrees.net](https://webtrees.net/) 1292. Unzip the files and upload them to an empty folder on your web server. 1303. Open your web browser and type the URL for your **webtrees** site (for example, 131 ``http://www.yourserver.com/webtrees`` into the address bar. 1324. The **webtrees** setup wizard will start automatically. Simply follow the steps, 133 answering each question as you proceed. 134 135That's it! 136 137However, before you can use **webtrees**, you need at least one GEDCOM 138(family tree) file. If you have been doing your research using a desktop program 139such as Family Tree Maker, you can use it's “save as GEDCOM” function to create 140a GEDCOM file. If you are starting from scratch, then **webtrees** can create a 141GEDCOM file for you. 142 143On successful installation you will be taken to the 144 ``Control panel`` -> ``Manage family trees`` page where you can: 145 * UPLOAD a GEDCOM file from your local machine 146 * ADD a GEDCOM file from your server, (if your GEDCOM file is too large to upload, 147 you can copy it to the webtrees/data folder, and load it from there) 148 * CREATE a new, empty GEDCOM file 149 150There are *lots* of configuration options. You'll probably want to review the 151privacy settings first. Don't worry too much about all the other options - the 152defaults are good for most people. If you get stuck, there's lots of built-in 153help and you can get friendly advice from the [help](https://webtrees.net/forums) 154forum. 155 156 157### Upgrading 158 159Upgrading **webtrees** is quick and easy. It is strongly recommended that you 160upgrade your installation whenever a new version is made available. Even minor 161**webtrees** version updates usually contain a significant number of bug fixes 162as well as interface improvements and program enhancements. 163 164* **Automatic upgrade** 165 166 **webtrees** has an automatic upgrade facility. An administrator upon logging in 167will receive notification when a new version is available and an option to start 168the automatic upgrade. If for some reason the automatic upgrade should fail 169then a manual upgrade should be performed. 170 171* **Manual upgrade** 172 173 1. Now would be a good time to make a [backup](#backup). 174 2. Download the latest version of **webtrees** available from 175 [webtrees.net](https://webtrees.net/) 176 3. While you are in the middle of uploading the new files, 177 a visitor to your site would encounter a mixture of new and old files. This 178 could cause unpredictable behaviour or errors. To prevent this, create the 179 file **data/offline.txt**. While this file exists, visitors will see a 180 “site unavailable - come back later” message. 181 4. Unzip the .ZIP file, and upload the files to your web server, overwriting the existing files. 182 5. Delete the file **data/offline.txt** 183 184 185#### Note for Macintosh users 186 187Step 4 assumes you are using a copy tool that **merges** directories rather than 188replaces them. (**Merge** is standard behaviour on Windows and Linux.) If you use 189the Macintosh Finder or other similar tool to perform step 3, it will **replace** 190your configuration, media and other directories with the empty/default ones from 191the installation. This would be very bad (but you did take a backup in step 1, 192didn't you!). Further details and recommendations for suitable tools can be found 193by searching [google.com](http://google.com). 194 195 196#### Note for anyone using custom code (modules, themes, etc.). 197 198It is **very likely** that your custom code will not work when you upgrade 199**webtrees**. 200 201**We recommend that you disable all custom code before you apply the upgrade.** 202 203Disable custom modules, switch over to a standard theme, and remove any code “hacks”. 204Once the upgrade is complete and you are satisfied that your site is fully operational contact 205the source of those modules or themes for a new version. 206 207 208#### General note 209 210Depending on the changes in the new files, your browser configuration 211and possibly other factors, it is always wise to clear both the **webtrees** cache 212and your browser cache immediately after the upgrade is completed. The **webtrees** 213cache can be cleared simply by going to ``Control Panel`` -> ``Family Trees`` -> 214``Clean-up data folder`` and deleting the cache. 215 216If you have any problems or questions, help is available on the 217[webtrees forum](https://www.webtrees.net/index.php/en/forum). 218 219### Building and developing 220 221If you want to build webtrees from source, or modify the code, you'll need to install 222a couple of tools first. 223 224You will need [composer](https://getcomposer.org/) to install the PHP dependencies. 225Then run this command:: 226 227* php composer.phar install 228 229You will need [npm](https://www.npmjs.com/get-npm) to install the Javascript dependencies. 230Then run the commands: 231 232* npm install 233* npm run production 234 235You will need to re-run the second of these any time you modify the file `webtrees.js`. 236 237### Gedcom (family tree) files 238 239When you ADD or IMPORT a family tree (GEDCOM) file in **webtrees** the 240data from the file is transferred to the database tables. The file itself 241remains in the **webtrees/data** folder and is no longer used or required 242by **webtrees**. Any subsequent editing of the **webtrees** data 243will not change this file 244 245When or if you change your genealogy data outside of **webtrees**, it is not 246necessary to delete your GEDCOM file or database from **webtrees** and start 247over. Follow these steps to update a GEDCOM that has already been imported: 248 249* Go to ``Control panel`` -> ``Manage family trees`` On the line relating to this particular family tree (GEDCOM) 250 file (or a new one) select IMPORT. 251* Take careful note of the media items option (_“If you have created media objects 252 in **webtrees**, and have edited your data off-line using software that 253 deletes media objects, then tick this box to merge the current media objects 254 with the new GEDCOM.”_) In most cases you should leave this box **UNCHECKED**. 255* Click “SAVE”. **webtrees** will validate the GEDCOM again before importing. 256 During this process, **webtrees** copies your entire family tree (GEDCOM file) 257 to a 'chunk' table within your database. Depending on the coding of your file, 258 its file size and the capabilities of your server and the supporting software, 259 this may take some time. **No progress bar will show while the data is being 260 copied** and should you navigate away from this page, the process is suspended. 261 It will start again when you return to the Family Tree management page. 262 263 264#### Gedcom file Formats 265 266Every Family History program has its own method of creating GEDCOM files, and 267differing output format options to select from. **webtrees'** import routines 268can read many different formats, but not necessarily all. If your software has 269a “UTF8” option you should always use that. However, **webtrees** has been 270tested with these alternative formats: 271 272* ANSI 273 * imports OK, but is slow due to the translation into UTF8 as part 274 of the import process. 275* MAC 276 * imports OK, but is slow due to the translation into UTF8 as part 277 of the import process. 278* DOS 279 * imports OK, but is slow due to the translation into UTF8 as part 280 of the import process. 281* ANSEL 282 * currently will not import. Gives warning *Error: cannot convert 283 GEDCOM file from ANSEL encoding to UTF-8 encoding*. Later releases 284 of **webtrees** may include the facility to translate from ANSEL to UTF8, 285 but for now a standalone utility [is available here](https://dev.webtrees.net/ansel/) 286 and should be used to convert the format to UTF-8 prior to importing. 287 288 289### Security 290 291**Security** in _webtrees_ means ensuring your site is safe from unwanted 292intrusions, hacking, or access to data and configuration files. The developers 293of _webtrees_ regard security as an extremely important part of its development 294and have made every attempt to ensure your data is safe. 295 296The area most at risk of intrusion would be the **/data** folder that contains your 297config.ini.php file, and various temporary files. If you are concerned there 298may be a risk there is a very simple test you can do: try to fetch the file 299config.ini.php by typing **``url_to_your_server/data/config.ini.php``** in your web 300browser. 301 302The most likely result is an “access denied” message like this: 303 304 Forbidden 305 306 You don't have permission to access /data/config.ini.php on this server. 307 308This indicates that the protection built into **webtrees** is working, and no 309further action is required. 310 311In the unlikely event you do fetch the file (you will just see a semicolon), 312then that protection is not working on your site and you should take some further 313action. 314 315If your server runs PHP in CGI mode, then change the permission of the **/data** 316folder to 700 instead of 777. This will block access to the httpd process, 317while still allowing access to PHP scripts. 318 319This will work for perhaps 99% of all users. Only the remaining 1% should consider 320the most complex solution, moving the **/data** folder out of accessible web 321space. (**_Note:_** In many shared hosting environments this is not an option anyway.) 322 323If you do find it necessary, following is an example of the process required: 324 325If your home folder is something like **/home/username**, 326and the root folder for your web site is **/home/username/public_html**, 327and you have installed **webtrees** in the **public_html/webtrees** folder, 328then you would create a new **data** folder in your home folder at the same 329level as your public_html folder, such as **/home/username/private/data**, 330and place your GEDCOM (family tree) file there. 331 332Then change the **Data folder** setting on the ``Control panel`` -> 333``Website`` -> ``Website preferences`` page from the default **data/** to the new 334location **/home/username/private/data** 335 336You will have **two** data directories: 337 338* [path to webtrees]/data - just needs to contain config.ini.php 339* /home/username/private/data - contains everything else 340 341 342#### Hypertext Transfer Protocol Secure (HTTPS) 343 344**webtrees** supports https access. If your website is configured with mandatory 345or optional https support **webtrees** will operate correctly in either mode. 346 347If your website is configured with optional https support, **webtrees** can be 348configured to switch to https at login. To enable https at login, set the Sign-in 349URL setting on the ``Control panel`` -> ``Website`` -> 350``Sign-in and registration`` to your https login URL, which is often in the form 351**``url_to_your_server/data/admin.php``** 352 353**Warning:** Misconfiguration can disable your login links. If this occurs, 354access the login by typing the correct URL directly into your browser's address input. 355 356 357### Backup 358 359Backups are good. Whatever problem you have, it can always be fixed from a good 360backup. 361 362To make a backup of **webtrees**, you need to make a copy of the following 363 3641. The files in the *webtrees/data* folder. 3652. The files in the *webtrees/media* folder. 3663. The tables in the database. Freely available tools such as 367 [phpMyAdmin](http://www.phpmyadmin.net) allow you to do this in one click. 368 369Remember that most web hosting services do NOT backup your data, and this is 370your responsibility. 371
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}