Installation

The Fossil Calibrations website is built using a typical LAMP stack (Linux, Apache, MySQL, PHP). Here are the versions of each that we've used in development:

• CentOS 5.10 (32-bit)
• Apache 2.2.3
• MySQL 5.5.8
• PHP 5.4 with mysqlnd (Not available directly from CentOS 5/6 repos, use ius or remi.

These should be considered minimum versions in all cases. Newer versions should work as well or better, but may require tweaks to configuration or (rarely) source code.

Once these are in place, you'll need to:

1. Secure a domain name and install a matching SSL cert (possibly self-signed) for admin access.

2. Clone the FossilCalibrations repository. (I'm using /path/to/local/ in these examples, but you should replace this in all steps with something more sensible.)

cd /path/to/local
git clone git@github.com:NESCent/FossilCalibrations.git

3. Configure Apache to read the website from the root folder of the local repo. (This can usually be done in /etc/httpd/conf.d/ or /etc/apache2/httpd.conf or /etc/apache2/extras/httpd-vhosts.conf, depending on the apache version and your preferred layout.)

<VirtualHost *:80> 
   ServerAdmin admin@mysite.com 
   DocumentRoot /path/to/local/FossilCalibrations 
   ServerName fossils.mysite.com  
</VirtualHost>

4. Configure Apache to support secure admin access via HTTPS. (This might be done in /etc/httpd/conf.d/ or /etc/apache2/httpd.conf or /etc/apache2/extras/httpd-ssl.conf, depending on the apache version and your preferred layout.)

<VirtualHost _default_:443>
   DocumentRoot /path/to/local/FossilCalibrations
   ServerName fossils.mysite.com:443
   ...

5. Configure MySQL to support recursive stored procedures with thread_stack, UTF-8, and increasing the max_allowed_packet. (This is usually done in /etc/my.conf.)

[mysqld]
thread_stack = 1920K
collation-server = utf8_unicode_ci
init-connect='SET NAMES utf8'
character-set-server = utf8
max_allowed_packet = 32M

Recursive functions also rely on max_sp_recursion_depth, but this is handled in the code for each recursive procedure.

Since images are stored directly in the database, max_allowed_packet must be set so that the php code can insert base64-encoded versions of image files. The default for this field is too small for a 3MB PNG image.

6. As MySQL's root user, install the latest FCD database as FossilCalibration. This can most easily be done using simple dump + import operations from the latest dev site (or directly from the developers). NOTE that this database uses stored procedures extensively; moving these requires the --routines option to mysqldump!

Note: When creating the database, be sure to use UTF8:

CREATE DATABASE FossilCalibration DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;

[TODO: Provide a skeleton database in the repo. This should define the structure for all tables and supporting data in some, plus the latest triggers, functions, and stored procedures. This should supercede the migration scripts etc. in the repo's db/ directory. But the dump files are super-verbose and not great for grepping or editing...]

7. Configure PHP to support automatic session init for each request and enable short tags. (This is generally in /etc/php.ini, but as usual this file's location may vary.)

session.auto_start = 1
short_open_tag = On

While you're in this file, establish UTF-8 as the encoding throughout the site. (This matches the META element in header.php, and will help to enforce encoding in some browsers.)

default_charset = "utf-8"
mbstring.internal_encoding=utf-8
mbstring.http_output=UTF-8
mbstring.encoding_translation=On
mbstring.func_overload=6

For handling file uploads, set the following values:

post_max_size = 200M
upload_max_filesize = 200M
memory_limit = 1024M

8. Configure PHP with sensitive information.

• Copy config.php.EXAMPLE (in the site root) to the parent folder, renaming it config.php.
• Add usernames and passwords for MySQL and privileged website users.
• Replace any dummy values that include 'REPLACE' or 'EXAMPLE'.

9. Force all administrative pages to HTTPS. All potentially sensitive pages are in the /protected/ directory. To force requests on this path to use HTTPS, use Apache configuration or adapt the example .htaccess file found at protected/.htaccess.EXAMPLE. (This also includes code to force a login via Basic Auth, but this is no longer needed since PHP will force the user to log in before showing these admin pages.) Here's a minimal protected/.htaccess page used in the current dev site:

# Define domain and HTTPS port for the current site setup
# (default port for HTTPS is 443)
RewriteRule .* - [E=FCD_DOMAIN:fossils.ibang.com]
RewriteRule .* - [E=FCD_SECURE_PORT:443]

# Force all requests into this folder to HTTPS
RewriteEngine On
RewriteCond %{SERVER_PORT} 80
RewriteCond %{REQUEST_URI} protected
RewriteRule ^(.*)$ https://%{ENV:FCD_DOMAIN}:%{ENV:FCD_SECURE_PORT}/protected/$1 [R,L]

10. To put the entire site behind a login -- so that it's required even to view the home page -- use an .htaccess file in the web root directory. (This is not a likely requirement after the initial site launch.) Here's the current embargo file, which assumes an .htpassword file has been created with at least one user+password:

AuthName "FCD EMBARGO"
AuthType Basic
AuthUserFile /var/www/.htpasswd
require valid-user
ErrorDocument 401 "The Fossil Calibration Database is not yet available for public viewing. Please check back again soon."

11. Once all processes have been (re)started, the Fossil Calibrations website should now be available at the expected address.

12. Before users can browse or enter new calibrations, you'll need to login to the site as an administrator (using the login link in the site footer), then run these site maintenance tasks on the Admin Dashboard page:

• Rebuild all calibration trees
• Update searchable multitree
• Update calibrations-by-clade table
• Update auto-complete lists

(NOTE that the final task Upload and import NCBI taxonomy is a placeholder. Currently these uploads must be done manually, in a process that expects careful review.)