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.
The current version for use in installation scripts is: h5.1.1.beta (24 Feb 2019). We normally distribute the beta code since this has the latest bug fixes. Please discuss with us – support at heuristnetwork dot org – if you need an older version.
Version 5.x.x is compatible with PHP7 as well as PHP5 and entirely backward compatible with Version 4 – we no longer support or run version 4.
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.
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.
curl -l https://heuristplus.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.
Note: June 2018 – please see glitch under Gotchas below which requires you to run a separate script before running Heurist. Will be resolved in July 2018.
Note: In third quarter 2018 we will switch the link above to install code compatible with PHP7, and we will move all hosted databases to our https server.
curl -l https://heuristplus.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:
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.
Heurist requires external, external_h4, vendor, 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: external.tar.bz2, external_h4.tar.bz2, vendor.tar.bz2, and 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. Note: vendor is new in version 5.1.x (Feb 2019) and will gradually replace the other external library folders.
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:
local-infile = 1
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.
Mail (optional but strongly recommended): 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).
Cron (optional but strongly recommended): You should also set up cron jobs to carry out notifications and regeneration of fixed html files from custom reports. If you require this functionality, please send us an email and we will supply instructions.
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
Symptom: Get a message “Table ‘Heurist_DBs_index.sysUsers’ doesn’t exist”
Cause: This is a database which is specific to the University of Sydney servers which we have accidentally referenced. This error will be resolved in the next version July 2018 (V5.4.12)
Solution: run admin/setup/dbupgrade/centralIndex.php on your installation of Heurist.
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
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.