LiquidFeedback Installation Instructions

This document gives a short outline about the necessary steps to setup a LiquidFeedback system.

1. Install necessary dependencies

If you're using a Debian system, make sure that the following packages are installed:

If you're using any other Linux distribution or BSD system, install the necessary software components accordingly.

2. Ensure that the user account of your webserver has access to the database

Whichever useraccount is used by the webserver (usually www-data) needs to have access to your PostgreSQL installation. This is done by executing PostgreSQL's shell command createuser as database superuser (usually pgsql, or postgres for Debian installations):

su - postgres
createuser

Enter name of role to add: www-data
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

exit

3. Install and configure LiquidFeedback-Core

We recommend to create the database with the same user as your webserver (usually www-data) to avoid having to setup database privileges.

The example below installs the database as www-data and stores the two executables lf_update and lf_update_issue_order in the directory /opt/liquid_feedback_core/:

# Download and unpack LiquidFeedback-Core
# from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
make
mkdir /opt/liquid_feedback_core
cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core
su - www-data
cd /opt/liquid_feedback_core
createdb liquid_feedback
createlang plpgsql liquid_feedback  # command may be omitted, depending on PostgreSQL version
psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback

A simple configuration may look as follows:

psql liquid_feedback

INSERT INTO system_setting (member_ttl) VALUES ('1 year');
INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
INSERT INTO policy (index, name, admission_time, discussion_time, verification_time, voting_time, issue_quorum_num, issue_quorum_den, initiative_quorum_num, initiative_quorum_den) VALUES (1, 'Default policy', '8 days', '15 days', '8 days', '15 days', 10, 100, 10, 100);
INSERT INTO unit (name) VALUES ('Our organization');
INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);

If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:

INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');

Exit the psql interface by typing:

\q

And don't forget to quit the www-data shell:

exit

4. Install WebMCP

Note: Using Debian, it may be necessary to append -I /usr/include/lua5.1 at the end of the CFLAGS line in Makefile.options of the WebMCP source distibution:

# Download and unpack WebMCP
# from http://www.public-software-group.org/pub/projects/webmcp/
vi Makefile.options  # Debian requires  -I /usr/include/lua5.1  at end of CFLAGS line
make
mkdir /opt/webmcp
cp -RL framework/* /opt/webmcp/

5. Install the LiquidFeedback-Frontend

Unpack source tree into appropriate directory, e.g. /opt/liquid_feedback_frontend:

# Download LiquidFeedback-Frontend
# from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend

Create HTML code for help texts:

cd /opt/liquid_feedback_frontend/locale
PATH=/opt/rocketwiki-lqfb:$PATH make

Make tmp/ directory of LiquidFeedback-Frontend writable for webserver:

chown www-data /opt/liquid_feedback_frontend/tmp

Compile binary for fast delivery of member images:

cd /opt/liquid_feedback_frontend/fastpath
vi getpic.c  # check and modify #define commands as necessary
make

6. Configure mail system

It may be necessary to configure your server's mail system, e.g. running dpkg-reconfigure exim4-config on a Debian system.

7. Configure the Webserver for LiquidFeedback:

A sample configuration for lighttpd is given below (assuming mod_alias has been included elsewhere):

server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")

# Enable CGI-Execution of *.lua files through lua binary
cgi.assign += ( ".lua" => "/usr/bin/lua5.1" )

alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/",
               "/lf/static"    => "/opt/liquid_feedback_frontend/static",
               "/lf"           => "/opt/webmcp/cgi-bin" )

# Configure environment for demo application
$HTTP["url"] =~ "^/lf" {
  setenv.add-environment += (
    "LANG" => "en_US.UTF-8",
    "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/",
    "WEBMCP_CONFIG_NAME"  => "myconfig")
}

# URL beautification
url.rewrite-once += (
  # do not rewrite static URLs
      "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1",
      "^/lf/static/(.*)$"   => "/lf/static/$1",

  # dynamic URLs
      "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3",

)

$HTTP["url"] =~ "^/lf/fastpath/" {
  cgi.assign = ( "" => "" )
  setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" )
}

If you're using Debian, you may want to create a file with the name /etc/lighttpd/conf-available/60-liquidfeedback.conf and create a softlink in /etc/lighttpd/conf-enabled/.

8. Configure the LiquidFeedback-Frontend:

cd /opt/liquid_feedback_frontend/config
cp example.lua myconfig.lua
# edit myconfig.lua according to your needs

Use the following option in your configuration file to enable fast image loading:

config.fastpath_url_func = function(member_id, image_type)
  return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)
end

9. Setup regular execution of lf_update and related commands

The executables lf_update, lf_update_issue_order, and lf_update_suggestion_order must be executed regularly. This may be achieved by creating a file named /opt/liquid_feedback_core/lf_updated with the following contents:

#!/bin/sh

PIDFILE="/var/run/lf_updated.pid"
PID=$$

if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then
  echo "lf_updated is already running."
  exit 1
fi

echo "${PID}" > "${PIDFILE}"

while true; do
  su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
  su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
  su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
  sleep 5
done

This file must be marked as executable:

chmod +x /opt/liquid_feedback_core/lf_updated

And this file should be started automatically at system boot.

10. Setup notification loop in background

In addition to regular execution of lf_update and lf_update_suggestion_order, the following commands should be executed in background:

su - www-data
cd /opt/liquid_feedback_frontend/
echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig

11. Start the sytem

After lf_update has been executed at least once, and the webserver has been restarted (using the configuration above), you should be able to access your LiquidFeedback system.