bsw@1045: bsw@1045: jbe@1046: LiquidFeedback Installation Instructions bsw@1045: bsw@1045: jbe@1046:

LiquidFeedback Installation Instructions

jbe@1046: jbe@1046:

This document gives a short outline about the necessary steps to setup a jbe@1046: LiquidFeedback system.

jbe@1046: jbe@1046:

1. Install necessary dependencies

jbe@1046: jbe@1046:

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

jbe@1046: bsw@1045: jbe@1046: jbe@1046:

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

jbe@1046: jbe@1046:

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

jbe@1046: jbe@1046:

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

jbe@1046: bsw@1045: 
su - postgres
bsw@1045: createuser
bsw@1045: 
bsw@1045: Enter name of role to add: www-data
bsw@1045: Shall the new role be a superuser? (y/n) n
bsw@1045: Shall the new role be allowed to create databases? (y/n) y
bsw@1045: Shall the new role be allowed to create more new roles? (y/n) n
bsw@1045: 
jbe@1046: exit
jbe@1046:
jbe@1046: jbe@1046:

3. Install and configure LiquidFeedback-Core

jbe@1046: jbe@1046:

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

jbe@1046: jbe@1046:

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

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

A simple configuration may look as follows:

jbe@1046: bsw@1045: 
psql liquid_feedback
bsw@1045: 
jbe@1046: INSERT INTO system_setting (member_ttl) VALUES ('1 year');
jbe@1046: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
jbe@1046: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
jbe@1046: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
jbe@1046: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
jbe@1046: 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);
jbe@1046: INSERT INTO unit (name) VALUES ('Our organization');
jbe@1046: INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
jbe@1046: INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
jbe@1046:
jbe@1046: bsw@1045:

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

jbe@1046: jbe@1046: 
INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
jbe@1046:
jbe@1046: bsw@1045:

Exit the psql interface by typing:

jbe@1046: jbe@1046: 
\q
jbe@1046:
jbe@1046: bsw@1045:

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

jbe@1046: jbe@1046: 
exit
jbe@1046:
jbe@1046: jbe@1046:

4. Install WebMCP

jbe@1046: jbe@1046:

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

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

5. Install the LiquidFeedback-Frontend

bsw@1045: bsw@1045:

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

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

Create HTML code for help texts:

jbe@1046: bsw@1045: 
cd /opt/liquid_feedback_frontend/locale
jbe@1046: PATH=/opt/rocketwiki-lqfb:$PATH make
jbe@1046:
jbe@1046: bsw@1045:

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

jbe@1046: jbe@1046: 
chown www-data /opt/liquid_feedback_frontend/tmp
jbe@1046:
jbe@1046: bsw@1045:

Compile binary for fast delivery of member images:

jbe@1046: bsw@1045: 
cd /opt/liquid_feedback_frontend/fastpath
bsw@1045: vi getpic.c  # check and modify #define commands as necessary
jbe@1046: make
jbe@1046:
jbe@1046: jbe@1046:

6. Configure mail system

jbe@1046: jbe@1046:

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

jbe@1046: jbe@1046:

7. Configure the Webserver for LiquidFeedback:

jbe@1046: jbe@1046:

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

jbe@1046: jbe@1046: 
server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")
bsw@1045: 
bsw@1045: # Enable CGI-Execution of *.lua files through lua binary
jbe@1046: cgi.assign += ( ".lua" => "/usr/bin/lua5.1" )
bsw@1045: 
jbe@1046: alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/",
jbe@1046:                "/lf/static"    => "/opt/liquid_feedback_frontend/static",
jbe@1046:                "/lf"           => "/opt/webmcp/cgi-bin" )
bsw@1045: 
bsw@1045: # Configure environment for demo application
jbe@1046: $HTTP["url"] =~ "^/lf" {
bsw@1045:   setenv.add-environment += (
jbe@1046:     "LANG" => "en_US.UTF-8",
jbe@1046:     "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/",
jbe@1046:     "WEBMCP_CONFIG_NAME"  => "myconfig")
bsw@1045: }
bsw@1045: 
bsw@1045: # URL beautification
bsw@1045: url.rewrite-once += (
bsw@1045:   # do not rewrite static URLs
jbe@1046:       "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1",
jbe@1046:       "^/lf/static/(.*)$"   => "/lf/static/$1",
bsw@1045: 
bsw@1045:   # dynamic URLs
jbe@1046:       "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3",
bsw@1045: 
bsw@1045: )
bsw@1045: 
jbe@1046: $HTTP["url"] =~ "^/lf/fastpath/" {
jbe@1046:   cgi.assign = ( "" => "" )
jbe@1046:   setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" )
jbe@1046: }
jbe@1046:
jbe@1046: jbe@1046:

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

jbe@1046: jbe@1046:

8. Configure the LiquidFeedback-Frontend:

jbe@1046: bsw@1045: 
cd /opt/liquid_feedback_frontend/config
bsw@1045: cp example.lua myconfig.lua
jbe@1046: # edit myconfig.lua according to your needs
jbe@1046:
jbe@1046: jbe@1046:

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

jbe@1046: bsw@1045: 
config.fastpath_url_func = function(member_id, image_type)
jbe@1046:   return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)
jbe@1046: end
jbe@1046:
jbe@1046: jbe@1046:

9. Setup regular execution of lf_update and lf_update_suggestion_order

jbe@1046: jbe@1046:

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

jbe@1046: bsw@1045: 
#!/bin/sh
bsw@1045: 
jbe@1046: PIDFILE="/var/run/lf_updated.pid"
bsw@1045: PID=$$
bsw@1045: 
jbe@1046: if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then
jbe@1046:   echo "lf_updated is already running."
bsw@1045:   exit 1
bsw@1045: fi
bsw@1045: 
jbe@1046: echo "${PID}" > "${PIDFILE}"
bsw@1045: 
bsw@1045: while true; do
jbe@1046:   su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
jbe@1046:   su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
bsw@1045:   sleep 5
jbe@1046: done
jbe@1046:
jbe@1046: bsw@1045:

This file must be marked as executable:

jbe@1046: jbe@1046: 
chmod +x /opt/liquid_feedback_core/lf_updated
jbe@1046:
jbe@1046: bsw@1045:

And this file should be started automatically at system boot.

jbe@1046: jbe@1046:

10. Setup notification loop in background

jbe@1046: jbe@1046:

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

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

11. Start the sytem

jbe@1046: jbe@1046:

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

bsw@1045: bsw@1045: