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