QZ Forms

Installation

Prerequisites

A PostgreSQL database up and running
libpq accessed through <libpq-fe.h> - some systems include this in the PostgreSQL client package, others in a separate developement package.
libxml - you probably already have it
PCRE - for javascript style regex validation
fcgi - FastCGI development kit
A randomness source, either arc4random system call for BSD, getrandom for Linux > 3.17 or a /dev/random device file
A C compiler, gcc or clang
BSD Make, bmake to some. GNU make >= 4 also works.
A webserver that handles fastcgi
spawn-fcgi to start the daemon
A user and group to run as

Under OpenBSD:: pkg_add fcgi libxml pcre postgresql-client spawn-fcgi
Under Debian 9:: apt-get install gcc make libfcgi-dev postgresql libpq-dev libxml2-dev libpcre3-dev libssl-dev spawn-fcgi
Under FreeBSD 11:: pkg install libxml2 pcre postgresql10-client postgresql10-docs postgresql10-server fcgi-devkit spawn-fcgi

Basics

There is no configure script; you have to edit the Makefile.
A user and two groups need to be created.
There is an installation script that will setup a directory structure
There is database setup sql script to setup your PostgreSQL database
Your web server needs to be configured
Modify qzforms.conf for your database connection
A spawn-fcgi command line needs to be run to start qzforms

Makefile

In the top of the Makefile, the variable QZRANDOM has to be defined either as

To use the arc4random system call on BSD systems
```
    QZRANDOM=-DQZ_ARC4RANDOM
  
```
To use the getrandom system call on Linux >= 3.17
```
    QZRANDOM=-DQZ_GETRANDOM
  
```
To indicate a device file to use as a source of randomness
```
    QZRANDOM=-DQZ_RAND_DEV=\"/dev/urandom\"
  
```

There is no standard way of obtaining randomness, but there are many bad ways. If your system has the arc4random or getrandom system call, then that is prefered because it is faster. A device file such as /dev/random, /dev/arandom, or /dev/urandom can be specified otherwise; consult your system documentation for specifics.

Either clang or gcc can be specified in the CC variable.

To compile, run "make"

Install the Program

A user and two groups need to be created. A user and group "qzforms" to run the fastcgi application and a group formdev to allow form developers to read log files and edit templates.

Each system will have its variations, but on the authors system the following commands work:

Under OpenBSD:

groupadd qzforms
groupadd formdev
useradd -L daemon -s /usr/bin/false -g qzforms -d ${INSTALLDIR} qzforms

Under Debian 9:

groupadd qzforms
groupadd formdev
useradd -G daemon -s /usr/bin/false -g qzforms -d ${INSTALLDIR} qzforms

Under FreeBSD 11:

pw groupadd qzforms
pw groupadd formdev
pw useradd -n qzforms -c QZ Forms fastcgi application -d ${INSTALLDIR} \
    -g qzforms -L daemon -s /usr/bin/false

If you use names other than those above, then edit qzforms_install.sh appropriately.

The install script, qzforms_install.sh, will put the executable into the directory named on the command line. For example:

qzforms_install.sh /var/qzforms

drwxr-xr-x    8 root     qzforms       512 Nov 27 09:39 /var/qzforms
drwxr-x---    2 root     qzforms       512 Nov 27 09:39 /var/qzforms/config
-rw-r-----    1 root     qzforms      3069 Nov 27 09:39 /var/qzforms/config/qzforms.conf
drwxr-x---    2 root     qzforms       512 Nov 27 09:39 /var/qzforms/libexec
-r-xr-x---    1 root     qzforms    481292 Nov 27 09:39 /var/qzforms/libexec/qzforms.fcgi
-r-xr--r--    1 root     qzforms      1273 Nov 27 09:39 /var/qzforms/libexec/qzforms.init
drwxr-x---    2 qzforms  formdev       512 Nov 27 09:39 /var/qzforms/logs
drwxrwx---    2 qzforms  wheel         512 Nov 27 09:39 /var/qzforms/run
drwxrwx---    2 root     wheel         512 Nov 27 09:39 /var/qzforms/sql
-rw-rw----    1 root     wheel      135911 Nov 27 09:39 /var/qzforms/sql/qz_db_install_SV10.sql
-rw-rw----    1 root     wheel       19642 Nov 27 09:39 /var/qzforms/sql/qz_db_update_SV10.sql
-rw-rw----    1 root     wheel       39199 Nov 27 09:39 /var/qzforms/sql/qzforms_examples.sql
drwxrwxr-x    2 root     formdev       512 Nov 27 09:39 /var/qzforms/templates
-rw-rw-r--    1 root     formdev       468 Nov 27 09:39 /var/qzforms/templates/base.xml
-rw-rw-r--    1 root     formdev       405 Nov 27 09:39 /var/qzforms/templates/login.xml

Setup the database

There is a script qz_db_install_SV12.sql. Note the 12 is subject to change and represents the version of the database schema. Run the script from a psql command prompt while logged in as the database owner.

test1=> \i qz_db_install_SV12.sql

The necessary files are installed in a newly created schema, qz. If you would like to see them using commands such as \d, then modify the search path.

test1=> show search_path;
-[ RECORD 1 ]---------------
search_path | "$user",public
test1=> set search_path="$user",public,qz; 
SET
test1=> show search_path;
-[ RECORD 1 ]--------------------
search_path | "$user", public, qz

Or alternatively, modify the search_path in postgresql.conf.

There is also a qz_examples.sql script that will install a couple of example forms. The tables are installed into the public schema.

test1=> \i qz_examples.sql

The above script will add functionality to your qzforms installation by loading data into PostgreSQL.

For setting up PostgreSQL permissions, see Managing Users

Web Server

The web server needs to be configured to send a request to the fast-cgi server based on the first segment of the URL. So in http://example.com/qz/grid/edit qz is it.

In nginx:

location /qz/ {
    include  fastcgi_params;
    fastcgi_pass 127.0.0.1:9074;
    fastcgi_buffering off;
}

Use a port number that suits you, or use a unix domain socket.

For nginx, turn off buffering or large files or datasets will be served chopped.

spawn-fcgi startup

spawn-fcgi -a 127.0.0.1 -p 9074 -P /var/qzforms/run/qzforms.pid \
    -d /var/qzforms -u qzforms -g qzforms -- ./libexec/qzforms.fcgi

The address and port, -a and -p, match the webservers config or use -s for a Unix domain socket
/var/qzforms matches INSTALLDIR in the installation script
User and group, -u and -g, are the ids referenced in the install script.
The path relative to the startup directory, -d, to the config file matches the default in qzconfig.h, "config/qzforms.conf" by default. This can be modified by setting an environment variable QZ_CONFIG_FILENAME.
A sysV init script libexec/qzforms.init is provided. You may need to edit the top of the file for your installation.

Test it out

If all goes well, you should be able to point your web browser to http://example.com/qz/login and get a login page, login as the database owner, and get to a menu in qzforms.

For troubleshooting, look in your web server's error log and in the qzforms log.

Upgrading

For any Schema Version, there is a script to update the QZForms PostgreSQL data. The current Schema Version can be found in the table qz.constants, schema_version attribute. The update script has a name in the form of qz_db_update_SV4.sql, which for example will update the installation from Schema Version 3 to 4.

Because the database and the program have to be maintained in sync, running the update script has to be part of upgrading the server software.