Project

General

Profile

Installation

Dependencies

Database

Currently only the PostgreSQL database is officially supported - as this is the only database that has been tested.

Porting to other relational databases such as MySQL / MariaDB or SQLite should may work also however.

The details of how to install PostgreSQL or another database are beyond the scope of this document.

Perl modules

Several Perl modules are required.

  • Captcha::Authen
  • File::Spec
  • Email::Simple
  • Email::Simple::Creator
  • Email::Sender::Simple
  • DBI
  • DBD::Pg
  • HTML::Template
  • CGI
  • CGI::Session
  • Crypt::Random::Source
  • Crypt::Eksblowfish
  • MIME::Base32

On a Debian-based Linux system, most of the relevant modules can be installed with a command such as the following.

apt-get install libcaptcha-authen-perl libemail-simple-perl libemail-sender-perl libdbd-pg-perl \
libhtml-template-perl libcgi-session-perl libmime-base32-perl \
libcrypt-random-source-perl libcrypt-eksblowfish-perl

Unfortunately not all of the required modules are available as Debian packages, so you will have to install them another - e.g. using `cpan`.

cpan
get enum
make enum
install enum

Database

To create the PostgreSQL database, use the createdb command - as follows (replacing 'dbowner' and 'dbname' with the relevant values).

createdb -O dbowner dbname

Once you have created the relevant database, navigate to the 'db' sub-folder, and load the relevant database parameters by executing the commands in the SQL file provided.

cd db
psql < INSTALL-PG.sql dbname

Web server configuration

You will need to enable CGI scripts in the web server directory where the files are installed.

Configuration script(s) and pages

Once the database has been created, you will need to edit the local configuration files. To begin, you will need to switch to the relevant directory and copy the configuration templates.

  • Switch to the 'conf' directory.
  • Copy the 'site.cgi.template' file to 'site.cgi'.
  • Copy the 'db-conf.cgi.template' file to 'db-conf.cgi'.

Site variable configuration

In the 'site.cgi' file, edit the %site_cfg data structure as required. Specifically, you can set the administrator e-mail address, base directory, site URL, site name and a few other configuration variables in this associative array.

Be careful if changing the temporary and upload directories - as doing so may (in fact - as of May 2017 - probably will) break certain functionality on the site. It is best to leave these as they are unless you have unusual requirements.

Page and menu configuration

Again, in the 'site.cgi' file, configure the %pages data structure and @about_menu array as required. The @about_menu array determines which items will appear in the drop-down menu on the web browser interface. The URL links can be to static pages or, indeed, any URL you like.

The %pages data structure is used to map URLs to static HTML files in the 'pages' directory. You can add new pages or edit the existing pages there as you like, editing the @about_menu and %pages accordingly having done so.

Database configuration script

  • Open 'db-conf.cgi' and set the database name, username and password appropriately. Note that, as of October 2016, only PostgreSQL databases have been tested (corresponding to driver 'Pg').

CSS theme(s)

If you wish to use customise the CSS, do the following.

  • Copy the 'default' sub-folder in the 'css' folder to another sub-folder (e.g. 'css/local').
  • Open the file 'conf/site.cgi' and set the 'theme' variable to the name of your newly-created sub-folder (e.g. 'local').
  • Edit the CSS files in the newly-created sub-folder appropriately.

Directories for temporary files and uploads

Two directories are required for the storage of temporary files and uploads (e.g. photos). By default these are named 'tmp' and 'uploads' and are expected to be in the installation directory.

Permissions need to be set on these directories to allow your webserver (e.g. Apache or Nginx) to write to them. Assuming that your webserver runs as the 'www-data' user and group, something similar to the following commands could be used to create the directories and set appropriate permissions.

  • cd /var/www/niche-finder/
  • mkdir tmp
  • chown -R www-data.www-data tmp
  • mkdir uploads
  • chown -R www-data.www-data uploads

If your webserver runs as a different user then change the above commands as appropriate.