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.
Create a Heurist database (free institutionally-supported services)
These free services are kindly supported by Intersect Australia, Huma-Num (France) and contributions from users.
Heurist code
The current version running on our servers is /heurist/ which is updated automatically at 8am Sydney time (ie. in the middle of the night in Europe, afternoon/evening in N & S America) to align it with our installation – although updated daily it changes at irregular intervals of a few weeks. However we recommend specifying /h6-alpha/ in the update script on your server as this is updated daily at the same time with the latest fixes and improvements. The alpha version fixes any troublesome bugs we are aware of and is generally as or more reliable than the stable version. We recommend using /h6-alpha/ for all setup and data entry work; if you report a problem it will normally be fixed the next day, or sooner if it is obstructive/serious, or a temporary workaround will be provided if necessary. There is a link on the h6-alpha interface to report a bug and immediatley switch to the /heurist/ version (and a link on the /heurist/ version to go the other way). For publication of websites we recommend the /heurist/ version, since /h6-alpha/ will later become /h7-alpha/, whereas /heurist/ will always remain valid.
The recommended procedure is to run the update with /h6-alpha/ on a daily cron job (sudo crontab -e) at a suitable time after our daily update (we suggest 4am in Europe, Africa and west, or 8am in Asia). This will create a version addressed as <server>/h6-alpha (assuming a simlink in /var/www/html/ pointing to HEURIST/h6-alpha which is the standard installation structure). This can be migrated to <server>/heurist (the standard address, also accessed via simlink) after you have checked that there are no problems with your websites on /h6-alpha/, in order to create a stable version for published websites, or you can run updates from the /heurist/ version to a temporary version at intervals, check and migrate to HEURIST/heurist.
Source code is on github, and /h6-alpha/ should always reflect the h6-dev branch.
Version 6 was released in Jan 2021. Versions 6.x.x are compatible with PHP7 and 8 as well as PHP5 and entirely backward compatible with databases from Heurist version 3 through 5 – we no longer support or run versions 3, 4 or 5. Version 6 is also compatible with MySQL 8 and with MariaDB, although we recommend MySQL rather than MariaDB because some complex facet queries are extremely slow on MariaDB.
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. (on the whole we do not recommend this as our installation is non-invasive – it installs everything in /var/www/html/HEURIST (the directory can be moved or renamed after installation) and intentionally avoids changing any server settings (some manual tweaking could be required, but that remains under your control).
Test Prerequisites
Heurist assumes that Linux, Apache, MySQL and PHP (LAMP stack) are installed and running, and requires some specific PHP modules (which may already exist on your server). Heurist installs in an independent directory and makes no changes to the server to avoid conflicts with existing installed software. Please see the Prerequisites section below for changes which might be required to Apache, MySQL and PHP INI files for optimal management, and for the PHP modules to be installed. Once Heurist has been installed, run https://<your server>/heurist/admin/verification/verifyInstallation.php to list any missing required modules.
Install
curl -l https://HeuristRef.net/HEURIST/DISTRIBUTION/install_heurist.sh | bash -s h6-alpha sudo
h6-alpha is the name of the version to be installed, and can be replaced with heurist or h6-beta. 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 etc. 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 https://HeuristRef.net/HEURIST/DISTRIBUTION/update_heurist.sh | bash -s h6-alpha sudo
This creates a separate instance of Heurist in the HEURIST directory with the name of the update version (if this is different from an existing version on the server, allowing it to be used in parallel with the existing version in this case). This can be replaced once the new version has been checked over. The distribution file can be found at:
version.tar.bz2
where version is the version. All current versions 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 6.x.x is backwards compatible with any version since version 3.0 (dating to 2010), although there may be some minor glitches with saved searches and custom formats.
Support files
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.
Prerequisites
Heurist runs under a standard Unix LAMP stack configuration (Apache, PHP, MySQL/MariaDB) on Debian, Ubuntu, RHEL and other Unix variants (it can also be run on Windows or Mac). We currently support PHP 5.6 – 7.3 and MySQL 5.7 – 8.0, although it should run on older versions from MySQL 5.1. 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.
Run https://[yourhost]/heurist/admin/verification/verifyInstallation.php to verify that all required extensions are installed. Most of them should be enabled by default. Some extensions such as pdo, pdo_sqlite, exif, xsl are required only for specific tasks (for in situ file import or faims import). Some, such as mbstring, may already be installed by default. Make sure the following PHP extensions are installed:
gd, pdo, mbstring, mysqli, json, session, dom, curl, xsl, SimpleXML, xml, apache2handler, pcre, filter, SPL, zip, 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
To increase max allowed size for media files or import data to be uploaded from the PHP default of 2 MBytes, make the following changes in php.ini file (to locate your php.ini type in command line use either php -r “phpinfo();” | grep php.ini or php –ini ).
upload_max_filesize=30M
post_max_size=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.
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.
In case of problems, please feel free to contact us.
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: 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
Manual update
- 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.