Installation Guide v4.2.x

From PGVWiki
Revision as of 02:29, 1 June 2012 by Ggpauly (talk | contribs) (→‎Requirements: updated PDO requirement)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
Phpgedview.png


This guide is for first-time installations. If you are upgrading an existing installation, see the article on Upgrading.

The latest release on the v4.2.x series is version 4.2.4. The release was made on 13 January, 2011.

We provide here a list of the requirements needed to install PhpGedView. We do not provide full details on how to install these since there are many dedicated websites providing such details and we would not do it justice in this guide. We assume you will have these requirements satisfied by your Internet Service Provider (ISP) or your chosen web hosting solution. If you are unsure, contact them to check if they do.

Quick Install

  • Contact your ISP or web host to ensure they are able to supply the requirements to run PhpGedView.
  • Download and unzip PhpGedView-all-4.2.4.zip into a directory named phpgedview on your computer.
  • Upload the phpgedview directory and all its contents to your web space using a method allowed by your ISP or web host.
  • On the webserver, change the permissions of the following files and directories to be writable by the web server:
config.php
index/*
media/
media/thumbs/
  • Point your browser to the directory where you uploaded your PhpGedView files (for example, http://www.yourserver.com/phpgedview/). You should now see a PhpGedView configuration screen. NOTE: make sure to have cookies enabled.
Configuration Screen
  • Enter the information required using the '?' help icons next to each label for guidance. You will need the MySQL database name, username and password provided by your ISP or web web host. Click "Save".
  • Enter the details of the PhpGedView administrator and click "Create User". 'NOTE: Password must be ≥ 6 characters.
Create Admin User
  • If you have not yet received any errors you will see a message like:
Configuration Complete
  • On the web server, change the permissions of the config.php file to be non-writable by the web server.
  • You now have a clean PhpGedView installation ready for adding a GEDCOM.

Requirements

Your ISP may provide you with the following services. If they do not, you will need to to find a suitable web hosting solution.

Web server
A web server such as apache is required to serve the web pages over the internet.
PHP v5.2+
Your web server needs to be running PHP version 5.2 or greater to generate dynamic HTML pages and use all of PhpGedView 4.2.x functions. A minimum 30 second script maximum execution is needed in your php.ini.
PDO

PHP Data Objects (PDO) extension to PHP must be installed and enabled. This is a standard part of PHP, and allows PHP to connect to databases. PDO improves performance, improves sqlite compatibility, and allows a wider range of databases to be used.

Database
You will need at least 1 database and a username and password to access it.
PhpGedView primarily supports MySQL, but has also been tested and shown to work with Postgresql, SQLite, and SQL-Server. The versions required for each of these databases is outlined below:
MySQL 4.1+
PostgreSQL 8.0+
SQLite available through PDO-SQLite which is included in PHP 5
MS SQL-Server 2003+
Web space
At least 20MB of web space on the web server. You will need more than this if you intend to store multimedia linked to individuals.
GD Graphics Library (optional)
You may wish to install the GD Graphics Library which can then be used by PhpGedView for image manipulation such as creating thumnails. This can be important in saving bandwidth if large images (photos and scanned documents) are used in the genealogy.
Freetype Library (optional)
If Freetype is installed, you will have access to the "Circle Diagram" in the Charts menu. You will also get better watermarking from the Media Firewall.
Calendar (optional)
This is required for Jewish dates/calendars wish to be used.
zlib (optional)
If the web server being used by your ISP or web host is the apache web server, it can be configured to send data over the internet in a compressed form using the zlib library - this will save bandwidth. To enable this compression, your ISP or web host needs to add the following lines to the php.ini file:
php_flag zlib.output_compression On
php_value zlib.output_compression_level 5

Alternatively, your ISP or web host may allow you to make these changes yourself. Simply create a file called .htaccess (including the leading dot) in your PhpGedView directory on the web server and add the above two lines to it.

Installation

You must be familiar with methods to transfer files to another computer.

The method used may depend on the OS and the settings of your web space provider as well as your own computer abilities. It is not possible to address every combination, thus we will address the most generic way to do so - the use of a graphical File Transfer Protocol (FTP) client. An example of a free, open source FTP client is FileZilla - feel free to explore other alternative clients.

We aim not detail how to use an FTP client as this is best addressed by the documentation of the client you choose to use. We will however, detail the tasks that need to be undertaken with the FTP client. Another alternative, if your web space provider allows it, is to use an SSH client. However, we assume that if you know about SSH, you will likely already know what to do, so we will not discuss it here.

Obtaining PhpGedView

There are several packages available for PhpGedView v4.2.x, and you should decide which is most appropriate for your needs.

Once you have downloaded the appropriate file to your own computer, you will need to unzip the file into a directory of it's own e.g. phpgedview

Uploading PhpGedView to Your Web Space

Next, you should use your FTP client to transfer the phpgedview directory and all it's contents to your web space. The contents of this directory is quite large (~37MB) so this could take some time depending on your internet connection speed. However, you probably won't need all those files. With careful pruning, the upload can be reduced to around 9MB. You can also use your host's control panel, such as cPanel, to upload the compressed zip or tarball archive and then extract it once it is on the server.

The phpgedview directory in your web space, will now be referred to as the "PhpGedView install directory".

Setting File Permissions

Main article: Setting File Permissions

In order for PhpGedView to function correctly, the web server hosting your PhpGedView installation needs to have the permission to save and modify files in a limited number of directories within your PhpGedView install directory. Your FTP client should be capable of allowing you to modify these permissions (called attributes in some clients). Briefly, you should make the following directories and files in your PhpGedView install directory writable by everyone: 

index/*            # comment: '*' means all files and folders in that directory
media/
media/thumbs/

Essentially, this will allow PhpGedView to save multimedia files on the server.

More Secure Permissions

If your web server is hosted on a Unix-like OS and you know enough about what permissions are and how to set them, you should set permissions rigidly for a more secure installation.

  1. Determine what "user group" the web server runs process as. e.g. Apache2 on Debian runs as "www-data" by default.
  2. Change the "ownership" of all directories and files under the PhpGedView install directory to be owned by you.
  3. Change the "group membership" of all directories and files under the PhpGedView install directory to be that of the web server.
  4. Ensure all directories and files under the PhpGedView install directory cannot be written by the group members.
  5. Set specified directories and files to be group writable.

If you have SSH access to your Unix-like web server, the following commands should take care of this. It assumes the web server is running with group membership of "www-data", and your username is YOUR_USERNAME): 

chown -R YOUR_USERNAME ./phpgedview/
chgrp -R www-data ./phpgedview/
chmod -R g-w ./phpgedview/
chmod g+w ./phpgedview/index/
chmod g+w ./phpgedview/media/
chmod g+w ./phpgedview/media/thumbs/

Online PhpGedView Configuration

There exists a tool in PhpGedView that allows you to make changes to the PhpGedView configuration, this needs to be performed to complete the installation.

In order to do this, the web server must have permissions to write to the config.php file in the PhpGedView install directory to be able to save the changes.

WARNING: you should set config.php permissions back to not writable by the web server immediately after performing the configuration! Failing to do so will leave your PhpGedView installation at risk!

NOTE: you need cookies enabled to run the install script. This is not checked for. Without cookies enabled the install script fails in ways that point to other issues like not having the config.php file write-able or not having proper access to the database.

  • Using the FTP client, set the permissions of config.php in the PhpGedView install directory to be writable by everyone. Alternatively, if you are using an SSH client you could issue the following command:
chmod g+w ./phpgedview/config.php
Configuration Screen
  • Enter all relevant information into the form, clicking the help ('?') icons for guidance. You will need the MySQL database name, username and password provided by your ISP or web host. Click "Save".
  • Extra Configuration tips for those with ISPs who do not host PHPGedview ( this advice relates to an ISP which uses the online control panel program called "cpanel" and the phpmyadmin and mysqldatabases utilities);

host name is "localhost", database name is "accountname_name of database", use mysqldatabases utility to create a database and then a user that can access the database. Again usernames may have been automatically prefixed with the ISP account name - use the mysqldatabases utility to see.

  • Enter the details of the PhpGedView administrator and click "Create User". 'NOTE: Password must be ≥ 6 characters.
Create Admin User


  • If you have not yet received any errors you will see a message like:
Configuration Complete
  • Using your FTP client, change the permissions of the config.php file to be non-writable. If you are using an SSH client, make the config.php file non-writable by the group:
chmod g-w ./phpgedview/config.php

Upgrading From a Previous Version

Go to this page for Upgrading. It is usually a reasonably straightforward process, but can vary widely depending on your OS, your ISP etc.

Post-Install Tasks and Configuration

License

PhpGedView: Genealogy Viewer

Copyright (C) 2002 to 2009 PGV Development Team. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See the file GPL.txt included with this software for more detailed licensing information.

Retrieved from "https://wiki.phpgedview.net/en/index.php?title=Installation_Guide_v4.2.x&oldid=12609"