xref: /webtrees/README.md (revision b108908174bafa493667672cfb8e9510f0750f22)
1![Latest version](https://img.shields.io/github/v/release/fisharebest/webtrees?sort=semver)
2![Licence](https://img.shields.io/github/license/fisharebest/webtrees)
3[![Unit tests](https://github.com/fisharebest/webtrees/actions/workflows/phpunit.yaml/badge.svg)](https://github.com/fisharebest/webtrees/actions/workflows/phpunit.yaml)
4[![codecov](https://codecov.io/gh/fisharebest/webtrees/branch/main/graph/badge.svg?token=zREQBP4GBs)](https://codecov.io/gh/fisharebest/webtrees)
5[![Translation status](https://translate.webtrees.net/widgets/webtrees/-/svg-badge.svg)](https://weblate.iet.open.ac.uk/projects/webtrees/webtrees/)
6[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fisharebest/webtrees/badges/quality-score.png?b=main)](https://scrutinizer-ci.com/g/fisharebest/webtrees/?branch=main)
7[![Code Climate](https://codeclimate.com/github/fisharebest/webtrees/badges/gpa.svg)](https://codeclimate.com/github/fisharebest/webtrees)
8[![StyleCI](https://github.styleci.io/repos/11836349/shield?branch=main)](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 Stardard
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
91## System requirements
92
93To install **webtrees**, you need:
94
95* A webserver. Apache, NGINX and IIS are the most common types. To use “Pretty URLs”, you will need to configure URL rewriting"
96* 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.
97* Approximately 100MB of disk space for the application files, plus whatever is
98  needed for your media files, GEDCOM files and database.
99* PHP 7.1 - 7.4. Servers with PHP 5.3 - 7.0 can use **webtrees** 1.7.
100   * PHP should be configured to allow sufficient server resources (memory and
101     execution time) for the size of your system. Typical requirements are:
102      * Small systems (500 individuals): 16–32 MB, 10–20 seconds
103      * Medium systems (5,000 individuals): 32–64 MB, 20–40 seconds
104      * Large systems (50,000 individuals): 64–128 MB, 40–80 seconds
105
106## Browser compatibility
107
108  **webtrees** is tested on recent versions of popular browsers such as Edge, Firefox,
109  Chrome, and Safari.  Support for other browsers and older versions is on a case-by-case basis.
110
111## Installation
112
1131. Download the .ZIP file for latest stable version from [github.com](https://github.com/fisharebest/webtrees/releases/latest).
1142. Unzip the files and then upload them to an empty folder on your web server.
1153. Open your web browser and type the URL for your **webtrees** site (for example,
116   ``https://www.yourserver.com/webtrees`` into the address bar.
1174. The **webtrees** setup wizard will start automatically.
118
119Your first task will be to create a family tree.
120
121If you have a GEDCOM file, you can import it into the tree. If not, just start
122entering your family tree.
123
124There are lots of configuration options. You'll probably want to review the
125privacy settings first. Don't worry too much about all the other options - the
126defaults are good for most people. If you get stuck, you can get friendly help
127and advice from the [help](https://webtrees.net/forums) forum.
128
129
130## Upgrading
131
132Upgrading **webtrees** is quick and easy. It is strongly recommended that you
133upgrade your installation whenever a new version is made available. Even minor
134**webtrees** version updates usually contain a significant number of bug fixes
135as well as interface improvements and program enhancements.
136
137* **Automatic upgrade**
138
139  **webtrees** has an automatic upgrade facility. An administrator upon logging in
140will receive notification when a new version is available and an option to start
141the automatic upgrade. If for some reason the automatic upgrade should fail
142then a manual upgrade should be performed.
143
144* **Manual upgrade**
145
146  1. Now would be a good time to make a [backup](#backup).
147  2. Download the latest version of **webtrees** available from
148   [webtrees.net](https://webtrees.net/)
149  3. While you are in the middle of uploading the new files,
150   a visitor to your site would encounter a mixture of new and old files. This
151   could cause unpredictable behavior or errors. To prevent this, create the
152   file **data/offline.txt**. While this file exists, visitors will see a
153   “site unavailable - come back later” message.
154  4. Unzip the .ZIP file, and upload the files to your web server, overwriting the existing files.
155  5. Delete the file **data/offline.txt**.
156
157
158### Note for Macintosh users
159
160Step 4 assumes you are using a copy tool that **merges** directories rather than
161replaces them. (**Merge** is standard behavior on Windows and Linux.) If you use
162the Macintosh Finder or other similar tool to perform step 3, it will **replace**
163your configuration, media and other directories with the empty/default ones from
164the installation. This would be very bad (but you did take a backup in step 1,
165didn't you!). Further details and recommendations for suitable tools can be found
166by searching [google.com](https://google.com).
167
168
169## Building and developing
170
171If you want to build webtrees from source, or modify the code, you'll need to install
172a couple of tools first.
173
174You will need [composer](https://getcomposer.org/) to install the PHP dependencies.
175Then run this command::
176
177* php composer.phar install
178
179You will need [npm](https://www.npmjs.com/get-npm) to install the Javascript dependencies.
180Then run the commands:
181
182* npm install
183* npm run production
184
185You will need to re-run the second of these any time you modify the file `webtrees.js`.
186
187## Gedcom (family tree) files
188
189When you import a family tree (GEDCOM) file in **webtrees** the
190data from the file is transferred to the database tables. The file itself
191remains in the **webtrees/data** folder and is no longer used or required
192by **webtrees**. Any subsequent editing of the **webtrees** data
193will not change this file
194
195When or if you change your genealogy data outside of **webtrees**, it is not
196necessary to delete your GEDCOM file or database from **webtrees** and start
197over. Follow these steps to update a GEDCOM that has already been imported:
198
199* Go to ``Control panel`` -> ``Manage family trees`` On the line relating to this particular family tree (GEDCOM)
200  file (or a new one) select IMPORT.
201* Take careful note of the media items option (_“If you have created media objects
202  in **webtrees**, and have edited your data off-line using software that
203  deletes media objects, then tick this box to merge the current media objects
204  with the new GEDCOM.”_) In most cases you should leave this box **UNCHECKED**.
205* Click “SAVE”. **webtrees** will validate the GEDCOM again before importing.
206  During this process, **webtrees** copies your entire family tree (GEDCOM file)
207  to a 'chunk' table within your database. Depending on the coding of your file,
208  its file size and the capabilities of your server and the supporting software,
209  this may take some time. **No progress bar will show while the data is being
210  copied** and should you navigate away from this page, the process is suspended.
211  It will start again when you return to the Family Tree management page.
212
213
214### Gedcom file Formats
215
216Every Family History program has its own method of creating GEDCOM files, and
217differing output format options to select from. **webtrees'** import routines
218can read many different formats, but not necessarily all. If your software has
219a “UTF8” option you should always use that. However, **webtrees** has been
220tested with these alternative formats:
221
222* ANSI
223   * imports OK, but is slow due to the translation into UTF8 as part
224     of the import process.
225* MAC
226   * imports OK, but is slow due to the translation into UTF8 as part
227     of the import process.
228* DOS
229   * imports OK, but is slow due to the translation into UTF8 as part
230     of the import process.
231* ANSEL
232   * currently will not import. Gives warning *Error: cannot convert
233     GEDCOM file from ANSEL encoding to UTF-8 encoding*. Later releases
234     of **webtrees** may include the facility to translate from ANSEL to UTF8,
235     but for now a standalone utility [is available here](https://dev.webtrees.net/ansel/)
236     and should be used to convert the format to UTF-8 prior to importing.
237
238
239## Security
240
241**Security** in _webtrees_ means ensuring your site is safe from unwanted
242intrusions, hacking, or access to data and configuration files. The developers
243of _webtrees_ regard security as an extremely important part of its development
244and have made every attempt to ensure your data is safe.
245
246The area most at risk of intrusion would be the **/data** folder that contains your
247config.ini.php file, and various temporary files. If you are concerned there
248may be a risk there is a very simple test you can do: try to fetch the file
249config.ini.php by typing **``url_to_your_server/data/config.ini.php``** in your web
250browser.
251
252The most likely result is an “access denied” message like this:
253
254    Forbidden
255
256    You don't have permission to access /data/config.ini.php on this server.
257
258This indicates that the protection built into **webtrees** is working, and no
259further action is required.
260
261In the unlikely event you do fetch the file (you will just see a semicolon),
262then that protection is not working on your site and you should take some further
263action.
264
265If your server runs PHP in CGI mode, then change the permission of the **/data**
266folder to 700 instead of 777. This will block access to the httpd process,
267while still allowing access to PHP scripts.
268
269This will work for perhaps 99% of all users. Only the remaining 1% should consider
270the most complex solution, moving the **/data** folder out of accessible web
271space. (**_Note:_** In many shared hosting environments this is not an option anyway.)
272
273If you do find it necessary, following is an example of the process required:
274
275If your home folder is something like **/home/username**,
276and the root folder for your web site is **/home/username/public_html**,
277and you have installed **webtrees** in the **public_html/webtrees** folder,
278then you would create a new **data** folder in your home folder at the same
279level as your public_html folder, such as **/home/username/private/data**,
280and place your GEDCOM (family tree) file there.
281
282Then change the **Data folder** setting on the ``Control panel`` ->
283``Website`` -> ``Website preferences`` page from the default **data/** to the new
284location **/home/username/private/data**
285
286You will have **two** data directories:
287
288* [path to webtrees]/data - just needs to contain config.ini.php
289* /home/username/private/data - contains everything else
290
291
292## Backup
293
294Backups are good. Whatever problem you have, it can always be fixed from a good
295backup.
296
297To make a backup of **webtrees**, you need to make a copy of the following
298
2991. The files in the *webtrees/data* folder.
3002. The tables in the database. Freely available tools such as
301   [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):
302
303    `mysqldump --host=[localhost] -u [username] -p[password] --databases [databasename] > dump_file.sql`
304
305    Note that '*-p[password]*' goes together with no space in between.
306
307
308Remember that most web hosting services do NOT backup your data, and this is
309your responsibility.
310
311## Restore from backup
312
313To restore a backup on a new server:
314
3151. Follow the steps in [Installation](#installation) to get a clean new installation.
316
3172. Replace the *data* folder with backup copy.
318
3193. 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):
320
321    `mysql -u [username] -p[password] [database_name] < [dump_file.sql]`
322
3234. Confirm the file *data/config.ini.php* contains to correct information to connect to the database and update it if needed.
324