Installation Guide

You do not need to install the software to use Heurist – most users will create their database(s) on one of the free services available. This page describes installation on a private physical/virtual server where greater control is required.

Heurist code

The current version for use in installation scripts is: h4.2.18.beta (15 Apr 2017)

If not logged in as root, add ‘sudo’ as shown—omit if logged in as root. The scripts below can be downloaded, edited (if required) and run locally where the server does not have access to the Internet or for greater control on file locations etc.

Test prerequisites

http://heurist.sydney.edu.au/HEURIST/DISTRIBUTION/verifyInstallation.zip

Heurist assumes that Linux, Apache, MySQL and PHP (LAMP stack) are installed and running. Please see the Prerequisites section below for changes required to Apache, MySQL and PHP INI files. Then download and unzip the PHP file in the zip file above and run it on your server to determine whether the required PHP extensions are installed.

Install

curl -l http://heurist.sydney.edu.au/HEURIST/DISTRIBUTION/install_heurist.sh | bash -s version sudo

The first parameter version (see top of page for the current version) is the name of the version to be installed. omit sudo if you run this as root This script sets up and copies all necessary files to the HEURIST directory. After installation, you will need to add MySQL login information and contact email addresses to the Heurist initialisation file (…/HEURIST/heuristConfigIni.php) before running Heurist. The installation script will give you instructions at the end. The script ONLY creates directories, sets permissions and copies files, it does not make other changes to the server, so it should not interfere with any other software.

Update

curl -l http://heurist.sydney.edu.au/HEURIST/DISTRIBUTION/update_heurist.sh | bash -s version sudo 

omit sudo if you run this as root This creates a separate instance of Heurist in the HEURIST directory with the name of the update version (see top of page for the current version), which can be used in parallel with the existing version. This can be replaced once the new version has been checked over. The distribution file can be found at:

http://heurist.sydney.edu.au/HEURIST/DISTRIBUTION/version.tar.bz2

where version is the version (see top of page for the current version). All current versions (3.x.x and 4.x.x) operate on a compatible database structure, so one can switch to and fro between versions freely without problems, accessing the same database in each case. Thus it is OK to operate on an alpha version and switch back to a beta or production version if a problem is encountered. Heurist version 4.0 is forwards and backwards compatible with any version since 3.0, although some Heurist 4 functions will be missing when using Heurist 3.

Support files

Heurist requires external, external_h4, and help directories, normally installed in /var/www/html/HEURIST/HEURIST_SUPPORT and simlinked from the root folder of each Heurist codebase. They are located at: ternal.tar.bz2, external_h4.tar.bz2, help.tar.bz2. They are not included in the program’s tar.bz2 files (above), but are downloaded and installed automatically by the installation and update scripts.

Prerequisites

Heurist runs under a standard Unix LAMP stack configuration (Apache, PHP, MySQL) on Debian, Ubuntu, RHEL and other Unix variants (it can also be run on Windows or Mac). We currently support PHP 5.0 – 5.3 and MySQL 5.1 – 5.6, although it should run on older versions, having started off in MySQL 4. You may be able to install all three at once with lamp-stack, or else install the three components separately with sudo yum install … or sudo apt-get install … Please search the web for instructions for your particular operating system. Be sure to run /usr/bin/mysql_secure_installation to set the root password and remove default user and database.

Install the following PHP extensions. Some, such as mbstring, may already be installed by default.  See test at top of this page which will show you which extensions still need installing.

From Vsn 3: memcache, gd, pdo, mbstring
Required Vsn 4: mysql, mysqli, json, session, dom, curl, xsl, SimpleXML, xml, apache2handler, pcre, filter, SPL, zip
Optional Vsn 4: pdo_sqlite (for faims import), exif (for in situ file import)

In /etc/my.cnf or /etc/mysql/my.cnf add:

[mysqld]

local-infile = 1

[mysql]

local-infile = 1

Make the following changes to the php.ini file found in either /etc/php.ini or /etc/php5/apache2/php.ini

max_execution_time=300 session.gc_maxlifetime=2600000 date.timezone=”<your time zone>” short_open_tag = On upload_max_filesize=30M post_max_size=30M

Timeout of 5 minutes is desirable for some data import functions. Session timeout 30 days avoids having to login again every time you open a database unless it has been unused for a month. Upload and Post maximum sizes have a 2M default so we suggest increasing to 30M; the max size can be increased further, but it is better to use the multi-file uploader for very large files as it uploads in chunks and handles errors in transmission. Short_open_tag allows the use of <?= tags in the code. Setting date and time zone explicitly avoids lots of messages in the error log if this is incorrectly set by the system.

Finally, you should edit /etc/httpd/conf/httpd.conf and replace AllowOverride None with AllowOverride Limit Options=Indexes inside the <Directory “/var/www/html”> section. This enables .htaccess files which are used to restrict access to uploaded files and other user data, but permit web access to record type icons, image thumbnails and html output.

Once the pre-requisites are loaded, simply run the Heurist install script and you’re ready to roll. Certain functions (new user registration, notifications and sharing) require Heurist to send email. You can install a local email server with: apt-get install postfix (Debian) or yum install postfix (Redhat)

Multi-tier install

Heurist can be installed on a tiered server installation, separating the web server from database and file servers, but there are a number of special steps required which cannot be standardised in an installation script since the system design will vary..

  • The database server must be accessible to the web server (and preferably to no other server) through the MySQL port;
  • The filestore server will need to be mounted on the web server so that the files are accessible to the program scripts. Ideally the web server is the only server to which the filestore server is exposed;
  • The NFS server must be modified so that it exports files as the same user that Apache uses. To do this we need to first create the account and group as follows:

Create the Apache group:

On Redhat: groupadd apache -og 48

On Debian: groupadd www-data -og 33

Create the Apache user:

Redhat: useradd www-data -u 48 -c apache -og apache -G apache -d /var/www -s /sbin/nologin

Debian: useradd apache -u 33 -c www-data -og www-data -G www-data -d /var/www -s /sbin/nologin

Change ownership of /HEURIST_FILESTORE

Redhat: chown -R apache:apache /HEURIST_FILESTORE

Debian: chown -R www-data:www-data /HEURIST_FILESTORE

Gotchas

Symptom: keeps on asking you to login even though you have checked the box for remembering login for a month.
Cause: Unable to write in the PHP sessions folder ( /var/lib/php5 ).
Solution: should be owned and writable by apache or www-data according to operating system.

Symptom: Various errors, such as uncaught reference error, with no obvious pattern.
Cause: one of the simlinked support files in the root directory of the instance is missing.
Solution: Create simlinks for ext, external_h4 and help directories in the root of the instance.

Symptom: when you save a record, it writes out the record (the date and title change) but all the changes to data values disappear.
Cause: This occurs when migrating from old (3.0.x) to newer versions due to replacement of platform-specific stored procedures with cross-platform procedures.
Solution: simply run the following script in MySQL: migrated/admin/setup/dbcreate/addProceduresTriggers.sql

Manual update

You should not need to do this, but it is supplied for completeness.

  • Download the new version from (where xxxxx is the version)
  • Download the support functions from here
  • Make a new directory for the new version at the same level as the existing version(s)
  • Untar the distribution download into this new directory
  • Untar the support files into /var/www/html/HEUIRIST/HEURIST_SUPPORT
  • Add simlinks to ‘external_h4’ as ‘ext’ in the root of the codebase, and to ‘external’ and ‘help’ as simlinks in the ‘migrated’ subdirectory
  • We recommend using a heuristConfigIni.php file (prototype in the root of the Heurist distribution) placed in the Heurist parent directory (eg. /var/www/html/HEURIST) to override individual settings (see documentation_and_templates/directory_structure.txt file in Heurist codebase for full instructions). If you do not use this file you will need to edit configIni.php for each individual installed version (these can also be used to override settings for individual instances).
  • Run Heurist from the new directory
  • Delete old version and rename new version when satisfied that the new one is operating correctly.

Heurist Registration

Registration allows creation of Heurst databases and subscribes you to occasional news updates (single-click to unsubscribe).

We will not share your email information with any third party.

Thank you for registering. We have sent you an email, allowing you to confirm your registration and create your first Heurist database.