bsw@1045: LiquidFeedback Installation Instructions bsw@1045: ======================================== bsw@1045: bsw@1045: This document gives a short outline about the necessary steps to setup a bsw@1045: LiquidFeedback system. bsw@1045: bsw@1045: bsw@1045: 1. Install necessary dependencies bsw@1045: --------------------------------- bsw@1045: bsw@1045: If you're using a Debian system, make sure that the following packages are bsw@1045: installed: bsw@1045: jbe@1156: * build-essential jbe@1156: * lua5.2 jbe@1156: * liblua5.2-dev bsw@1045: * postgresql bsw@1045: * libpq-dev jbe@1156: * lighttpd (only for WebMCP 1.2.x support) bsw@1045: * imagemagick bsw@1045: * exim4 jbe@1046: * markdown2 (install with Python's pip) bsw@1045: bsw@1045: If you're using any other Linux distribution or BSD system, install the bsw@1045: necessary software components accordingly. bsw@1045: bsw@1045: bsw@1045: 2. Ensure that the user account of your webserver has access to the database bsw@1045: ---------------------------------------------------------------------------- bsw@1045: jbe@1156: The useraccount of the webserver (usually `www-data`) or the Moonbridge server jbe@1156: process needs to have access to your PostgreSQL installation. This is done by jbe@1156: executing PostgreSQL's shell command `createuser` as database superuser jbe@1156: (usually `pgsql`, or `postgres` for Debian installations): bsw@1045: 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: bsw@1045: exit bsw@1045: bsw@1045: bsw@1045: 3. Install and configure LiquidFeedback-Core bsw@1045: -------------------------------------------- bsw@1045: bsw@1045: We recommend to create the database with the same user as your webserver bsw@1045: (usually `www-data`) to avoid having to setup database privileges. bsw@1045: bsw@1045: The example below installs the database as `www-data` and stores the two bsw@1045: executables `lf_update` and `lf_update_issue_order` in the directory bsw@1045: `/opt/liquid_feedback_core/`: bsw@1045: 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 bsw@1045: psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback bsw@1045: bsw@1045: A simple configuration may look as follows: bsw@1045: bsw@1045: psql liquid_feedback bsw@1045: bsw@1045: INSERT INTO system_setting (member_ttl) VALUES ('1 year'); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120); bsw@1045: 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); bsw@1045: INSERT INTO unit (name) VALUES ('Our organization'); bsw@1045: INSERT INTO area (unit_id, name) VALUES (1, 'Default area'); bsw@1045: INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE); bsw@1045: bsw@1045: If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement: bsw@1045: bsw@1045: INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1'); bsw@1045: bsw@1045: Exit the `psql` interface by typing: bsw@1045: bsw@1045: \q bsw@1045: bsw@1045: And don't forget to quit the `www-data` shell: bsw@1045: bsw@1045: exit bsw@1045: bsw@1045: jbe@1156: 4. Install Moonbridge (only for WebMCP 2.x) jbe@1156: ------------------------------------------- jbe@1156: jbe@1156: # Download and unpack Moonbridge jbe@1156: # from http://www.public-software-group.org/pub/projects/moonbridge/ jbe@1156: pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua jbe@1156: mkdir /opt/moonbridge jbe@1156: cp moonbridge /opt/moonbridge/ jbe@1156: cp moonbridge_http.lua /opt/moonbridge/ jbe@1156: jbe@1156: jbe@1156: 5. Install WebMCP bsw@1045: ----------------- bsw@1045: jbe@1156: Note: Using Debian, it may be necessary to append `-I /usr/include/lua5.2` at bsw@1045: the end of the CFLAGS line in `Makefile.options` of the WebMCP source bsw@1045: distibution: bsw@1045: bsw@1045: # Download and unpack WebMCP bsw@1045: # from http://www.public-software-group.org/pub/projects/webmcp/ jbe@1156: vi Makefile.options # Debian requires -I /usr/include/lua5.2 at end of CFLAGS line bsw@1045: make bsw@1045: mkdir /opt/webmcp bsw@1045: cp -RL framework/* /opt/webmcp/ bsw@1045: bsw@1045: jbe@1156: 6. Install the LiquidFeedback-Frontend bsw@1045: -------------------------------------- bsw@1045: bsw@1045: Unpack source tree into appropriate directory, e.g. `/opt/liquid_feedback_frontend`: bsw@1045: bsw@1045: # Download LiquidFeedback-Frontend bsw@1045: # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/ bsw@1045: mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend bsw@1045: bsw@1045: Make `tmp/` directory of LiquidFeedback-Frontend writable for webserver: bsw@1045: bsw@1045: chown www-data /opt/liquid_feedback_frontend/tmp bsw@1045: jbe@1156: Compile binary for fast delivery of member images (only necessary for WebMCP 1.2.x): bsw@1045: bsw@1045: cd /opt/liquid_feedback_frontend/fastpath bsw@1045: vi getpic.c # check and modify #define commands as necessary bsw@1045: make bsw@1045: bsw@1045: jbe@1156: 7. Configure mail system bsw@1045: ------------------------ bsw@1045: bsw@1045: It may be necessary to configure your server's mail system, e.g. running bsw@1045: `dpkg-reconfigure exim4-config` on a Debian system. bsw@1045: bsw@1045: jbe@1156: 8. Configure the Webserver for LiquidFeedback (only for WebMCP 1.2.x) jbe@1156: --------------------------------------------------------------------- bsw@1045: bsw@1045: A sample configuration for `lighttpd` is given below (assuming `mod_alias` has bsw@1045: been included elsewhere): bsw@1045: bsw@1045: server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv") bsw@1045: bsw@1045: # Enable CGI-Execution of *.lua files through lua binary bsw@1045: cgi.assign += ( ".lua" => "/usr/bin/lua5.1" ) bsw@1045: bsw@1045: alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/", bsw@1045: "/lf/static" => "/opt/liquid_feedback_frontend/static", bsw@1045: "/lf" => "/opt/webmcp/cgi-bin" ) bsw@1045: bsw@1045: # Configure environment for demo application bsw@1045: $HTTP["url"] =~ "^/lf" { bsw@1045: setenv.add-environment += ( bsw@1045: "LANG" => "en_US.UTF-8", bsw@1045: "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/", bsw@1045: "WEBMCP_CONFIG_NAME" => "myconfig") bsw@1045: } bsw@1045: bsw@1045: # URL beautification bsw@1045: url.rewrite-once += ( bsw@1045: # do not rewrite static URLs bsw@1045: "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1", bsw@1045: "^/lf/static/(.*)$" => "/lf/static/$1", bsw@1045: bsw@1045: # dynamic URLs bsw@1045: "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3", bsw@1045: bsw@1045: ) bsw@1045: bsw@1045: $HTTP["url"] =~ "^/lf/fastpath/" { bsw@1045: cgi.assign = ( "" => "" ) bsw@1045: setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" ) bsw@1045: } bsw@1045: bsw@1045: If you're using Debian, you may want to create a file with the name bsw@1045: `/etc/lighttpd/conf-available/60-liquidfeedback.conf` and create a softlink in bsw@1045: `/etc/lighttpd/conf-enabled/`. bsw@1045: bsw@1045: jbe@1156: 9. Configure the LiquidFeedback-Frontend jbe@1156: ---------------------------------------- bsw@1045: bsw@1045: cd /opt/liquid_feedback_frontend/config bsw@1045: cp example.lua myconfig.lua bsw@1045: # edit myconfig.lua according to your needs bsw@1045: bsw@1045: Use the following option in your configuration file to enable fast image jbe@1156: loading (only for WebMCP 1.2.x): bsw@1045: bsw@1045: config.fastpath_url_func = function(member_id, image_type) bsw@1045: return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type) bsw@1045: end bsw@1045: bsw@1045: jbe@1156: 10. Setup regular execution of `lf_update` and related commands jbe@1156: --------------------------------------------------------------- bsw@1045: jbe@1051: The executables `lf_update`, `lf_update_issue_order`, and jbe@1051: `lf_update_suggestion_order` must be executed regularly. This may be achieved jbe@1051: by creating a file named `/opt/liquid_feedback_core/lf_updated` with the jbe@1051: following contents: bsw@1045: bsw@1045: #!/bin/sh bsw@1045: bsw@1045: PIDFILE="/var/run/lf_updated.pid" bsw@1045: PID=$$ bsw@1045: bsw@1045: if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then bsw@1045: echo "lf_updated is already running." bsw@1045: exit 1 bsw@1045: fi bsw@1045: bsw@1045: echo "${PID}" > "${PIDFILE}" bsw@1045: bsw@1045: while true; do bsw@1045: su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"' jbe@1051: su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"' bsw@1045: 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 bsw@1045: done bsw@1045: bsw@1045: This file must be marked as executable: bsw@1045: bsw@1045: chmod +x /opt/liquid_feedback_core/lf_updated bsw@1045: bsw@1045: And this file should be started automatically at system boot. bsw@1045: bsw@1045: jbe@1156: 11. Setup notification loop in background (only for WebMCP 1.2.x) jbe@1156: ----------------------------------------------------------------- bsw@1045: bsw@1045: In addition to regular execution of `lf_update` and bsw@1045: `lf_update_suggestion_order`, the following commands should be executed in bsw@1045: background: bsw@1045: bsw@1045: su - www-data bsw@1045: cd /opt/liquid_feedback_frontend/ bsw@1045: echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig bsw@1045: bsw@1045: jbe@1156: 12. Start the sytem bsw@1045: ------------------- bsw@1045: bsw@1045: After `lf_update` has been executed at least once, and the webserver has been bsw@1045: restarted (using the configuration above), you should be able to access your bsw@1045: LiquidFeedback system. bsw@1045: jbe@1156: If you use WebMCP 2.x, the server is started by calling: bsw@1045: jbe@1156: /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig jbe@1156: