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

The useraccount of the webserver (usually www-data) or the Moonbridge server process 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 -s $SHELL
createuser --no-superuser --createdb --no-createrole www-data
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 lf_update_suggestion_order /opt/liquid_feedback_core
su www-data -s $SHELL
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 Moonbridge (only for WebMCP 2.x)

# Download and unpack Moonbridge
# from http://www.public-software-group.org/pub/projects/moonbridge/
pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua
mkdir /opt/moonbridge
cp moonbridge /opt/moonbridge/
cp moonbridge_http.lua /opt/moonbridge/

5. Install WebMCP

Note: Using Debian, it may be necessary to append -I /usr/include/lua5.2 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.2  at end of CFLAGS line
make
mkdir /opt/webmcp
cp -RL framework/* /opt/webmcp/

6. 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

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 (only necessary for WebMCP 1.2.x):

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

7. 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.

8. Configure the Webserver for LiquidFeedback (only for WebMCP 1.2.x)

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/.

9. 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 (only for WebMCP 1.2.x):

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

10. 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 -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
  su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
  su - www-data -s /bin/sh -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.

11. Setup notification loop in background (only for WebMCP 1.2.x)

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

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

12. Start the system

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

If you use WebMCP 2.x, the server is started by calling:

su www-data -s $SHELL
/opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig

In the latter case, the Moonbridge server will open a TCP port according to your configuration. Directly accessing this TCP port through your webbrowser is helpful for development purposes. For real-life deployment, however, it is recommended to further proxy the application (e.g. using nginx). The proxy can also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge itself).

To start the Moonbridge as a background process, please refer to the Moonbridge command line options:

Get this help message: moonbridge {-h|--help}
Usage: moonbridge \
           [-b|--background] \
           [-d|--debug] \
           [-f|--logfacility {DAEMON|USER|0|1|...|7}] \
           [-i|--logident <syslog ident> \
           [-l|--logfile <logfile>] \
           [-p|--pidfile <pidfile>] \
           [-s|--stats] \
           -- <Lua script> [<cmdline options for Lua script>]