liquid_feedback_frontend
diff INSTALL.html @ 1045:701a5cf6b067
Imported LiquidFeedback Frontend 3.0 branch
| author | bsw |
|---|---|
| date | Thu Jul 10 01:19:48 2014 +0200 (2014-07-10) |
| parents | |
| children | b9300c2e75da |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/INSTALL.html Thu Jul 10 01:19:48 2014 +0200 1.3 @@ -0,0 +1,191 @@ 1.4 +<html> 1.5 +<head> 1.6 + <title>LiquidFeedback Installation Instructions</title> 1.7 + <style type="text/css">code{white-space: pre;}</style> 1.8 +</head> 1.9 +<body> 1.10 +<h1 id="liquidfeedback-installation-instructions">LiquidFeedback Installation Instructions</h1> 1.11 +<p>This document gives a short outline about the necessary steps to setup a LiquidFeedback system.</p> 1.12 +<h2 id="install-necessary-dependencies">1. Install necessary dependencies</h2> 1.13 +<p>If you're using a Debian system, make sure that the following packages are installed:</p> 1.14 +<ul> 1.15 +<li>lua5.1</li> 1.16 +<li>postgresql</li> 1.17 +<li>build-essential</li> 1.18 +<li>libpq-dev</li> 1.19 +<li>liblua5.1-0-dev</li> 1.20 +<li>lighttpd</li> 1.21 +<li>ghc</li> 1.22 +<li>libghc6-parsec3-dev</li> 1.23 +<li>imagemagick</li> 1.24 +<li>exim4</li> 1.25 +</ul> 1.26 +<p>If you're using any other Linux distribution or BSD system, install the necessary software components accordingly.</p> 1.27 +<h2 id="ensure-that-the-user-account-of-your-webserver-has-access-to-the-database">2. Ensure that the user account of your webserver has access to the database</h2> 1.28 +<p>Whichever useraccount is used by the webserver (usually <code>www-data</code>) needs to have access to your PostgreSQL installation. This is done by executing PostgreSQL's shell command <code>createuser</code> as database superuser (usually <code>pgsql</code>, or <code>postgres</code> for Debian installations):</p> 1.29 +<pre><code>su - postgres 1.30 +createuser 1.31 + 1.32 +Enter name of role to add: www-data 1.33 +Shall the new role be a superuser? (y/n) n 1.34 +Shall the new role be allowed to create databases? (y/n) y 1.35 +Shall the new role be allowed to create more new roles? (y/n) n 1.36 + 1.37 +exit</code></pre> 1.38 +<h2 id="install-and-configure-liquidfeedback-core">3. Install and configure LiquidFeedback-Core</h2> 1.39 +<p>We recommend to create the database with the same user as your webserver (usually <code>www-data</code>) to avoid having to setup database privileges.</p> 1.40 +<p>The example below installs the database as <code>www-data</code> and stores the two executables <code>lf_update</code> and <code>lf_update_issue_order</code> in the directory <code>/opt/liquid_feedback_core/</code>:</p> 1.41 +<pre><code># Download and unpack LiquidFeedback-Core 1.42 +# from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/ 1.43 +make 1.44 +mkdir /opt/liquid_feedback_core 1.45 +cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core 1.46 +su - www-data 1.47 +cd /opt/liquid_feedback_core 1.48 +createdb liquid_feedback 1.49 +createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version 1.50 +psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback</code></pre> 1.51 +<p>A simple configuration may look as follows:</p> 1.52 +<pre><code>psql liquid_feedback 1.53 + 1.54 +INSERT INTO system_setting (member_ttl) VALUES ('1 year'); 1.55 +INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6); 1.56 +INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12); 1.57 +INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60); 1.58 +INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120); 1.59 +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); 1.60 +INSERT INTO unit (name) VALUES ('Our organization'); 1.61 +INSERT INTO area (unit_id, name) VALUES (1, 'Default area'); 1.62 +INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);</code></pre> 1.63 +<p>If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:</p> 1.64 +<pre><code>INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');</code></pre> 1.65 +<p>Exit the <code>psql</code> interface by typing:</p> 1.66 +<pre><code>\q</code></pre> 1.67 +<p>And don't forget to quit the <code>www-data</code> shell:</p> 1.68 +<pre><code>exit</code></pre> 1.69 +<h2 id="install-webmcp">4. Install WebMCP</h2> 1.70 +<p>Note: Using Debian, it may be necessary to append <code>-I /usr/include/lua5.1</code> at the end of the CFLAGS line in <code>Makefile.options</code> of the WebMCP source distibution:</p> 1.71 +<pre><code># Download and unpack WebMCP 1.72 +# from http://www.public-software-group.org/pub/projects/webmcp/ 1.73 +vi Makefile.options # Debian requires -I /usr/include/lua5.1 at end of CFLAGS line 1.74 +make 1.75 +mkdir /opt/webmcp 1.76 +cp -RL framework/* /opt/webmcp/</code></pre> 1.77 +<h2 id="install-rocketwiki-lqfb-edition">5. Install RocketWiki LqFb-Edition</h2> 1.78 +<pre><code># Download and unpack "RocketWiki LqFb-Edition" 1.79 +# from http://www.public-software-group.org/pub/projects/rocketwiki/liquid_feedback_edition/ 1.80 +make 1.81 +mkdir /opt/rocketwiki-lqfb 1.82 +cp rocketwiki-lqfb rocketwiki-lqfb-compat /opt/rocketwiki-lqfb/</code></pre> 1.83 +<p>If you experience problems with multi-byte encoding (UTF-8) later, then apply the following patch to both <code>rocketwiki-lqfb.hs</code> and <code>rocketwiki-lqfb-compat.hs</code> prior compilation:</p> 1.84 +<pre><code>--- rocketwiki-lqfb.hs 1.85 ++++ rocketwiki-lqfb.hs 1.86 +@@ -1,4 +1,6 @@ 1.87 + 1.88 ++import System.IO (hSetEncoding, stdin, stdout, utf8) 1.89 ++ 1.90 + import Text.ParserCombinators.Parsec 1.91 + import Control.Applicative ((<$>), (<*>)) 1.92 + import Data.List (intercalate) 1.93 +@@ -405,7 +407,10 @@ 1.94 + return htmlEntity 1.95 + 1.96 + 1.97 +-main = interact wikiParse 1.98 ++main = do 1.99 ++ hSetEncoding stdin utf8 1.100 ++ hSetEncoding stdout utf8 1.101 ++ interact wikiParse 1.102 + 1.103 + wikiParse str 1.104 + | success parseResult = html</code></pre> 1.105 +<h2 id="install-the-liquidfeedback-frontend">6. Install the LiquidFeedback-Frontend</h2> 1.106 +<p>Unpack source tree into appropriate directory, e.g. <code>/opt/liquid_feedback_frontend</code>:</p> 1.107 +<pre><code># Download LiquidFeedback-Frontend 1.108 +# from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/ 1.109 +mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend</code></pre> 1.110 +<p>Create HTML code for help texts:</p> 1.111 +<pre><code>cd /opt/liquid_feedback_frontend/locale 1.112 +PATH=/opt/rocketwiki-lqfb:$PATH make</code></pre> 1.113 +<p>Make <code>tmp/</code> directory of LiquidFeedback-Frontend writable for webserver:</p> 1.114 +<pre><code>chown www-data /opt/liquid_feedback_frontend/tmp</code></pre> 1.115 +<p>Compile binary for fast delivery of member images:</p> 1.116 +<pre><code>cd /opt/liquid_feedback_frontend/fastpath 1.117 +vi getpic.c # check and modify #define commands as necessary 1.118 +make</code></pre> 1.119 +<h2 id="configure-mail-system">7. Configure mail system</h2> 1.120 +<p>It may be necessary to configure your server's mail system, e.g. running <code>dpkg-reconfigure exim4-config</code> on a Debian system.</p> 1.121 +<h2 id="configure-the-webserver-for-liquidfeedback">8. Configure the Webserver for LiquidFeedback:</h2> 1.122 +<p>A sample configuration for <code>lighttpd</code> is given below (assuming <code>mod_alias</code> has been included elsewhere):</p> 1.123 +<pre><code>server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv") 1.124 + 1.125 +# Enable CGI-Execution of *.lua files through lua binary 1.126 +cgi.assign += ( ".lua" => "/usr/bin/lua5.1" ) 1.127 + 1.128 +alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/", 1.129 + "/lf/static" => "/opt/liquid_feedback_frontend/static", 1.130 + "/lf" => "/opt/webmcp/cgi-bin" ) 1.131 + 1.132 +# Configure environment for demo application 1.133 +$HTTP["url"] =~ "^/lf" { 1.134 + setenv.add-environment += ( 1.135 + "LANG" => "en_US.UTF-8", 1.136 + "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/", 1.137 + "WEBMCP_CONFIG_NAME" => "myconfig") 1.138 +} 1.139 + 1.140 +# URL beautification 1.141 +url.rewrite-once += ( 1.142 + # do not rewrite static URLs 1.143 + "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1", 1.144 + "^/lf/static/(.*)$" => "/lf/static/$1", 1.145 + 1.146 + # dynamic URLs 1.147 + "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3", 1.148 + 1.149 +) 1.150 + 1.151 +$HTTP["url"] =~ "^/lf/fastpath/" { 1.152 + cgi.assign = ( "" => "" ) 1.153 + setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" ) 1.154 +}</code></pre> 1.155 +<p>If you're using Debian, you may want to create a file with the name <code>/etc/lighttpd/conf-available/60-liquidfeedback.conf</code> and create a softlink in <code>/etc/lighttpd/conf-enabled/</code>.</p> 1.156 +<h2 id="configure-the-liquidfeedback-frontend">9. Configure the LiquidFeedback-Frontend:</h2> 1.157 +<pre><code>cd /opt/liquid_feedback_frontend/config 1.158 +cp example.lua myconfig.lua 1.159 +# edit myconfig.lua according to your needs</code></pre> 1.160 +<p>Use the following option in your configuration file to enable fast image loading:</p> 1.161 +<pre><code>config.fastpath_url_func = function(member_id, image_type) 1.162 + return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type) 1.163 +end</code></pre> 1.164 +<h2 id="setup-regular-execution-of-lf_update-and-lf_update_suggestion_order">10. Setup regular execution of <code>lf_update</code> and <code>lf_update_suggestion_order</code></h2> 1.165 +<p>The executables <code>lf_update</code> and <code>lf_update_suggestion_order</code> must be executed regularly. This may be achieved by creating a file named <code>/opt/liquid_feedback_core/lf_updated</code> with the following contents:</p> 1.166 +<pre><code>#!/bin/sh 1.167 + 1.168 +PIDFILE="/var/run/lf_updated.pid" 1.169 +PID=$$ 1.170 + 1.171 +if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then 1.172 + echo "lf_updated is already running." 1.173 + exit 1 1.174 +fi 1.175 + 1.176 +echo "${PID}" > "${PIDFILE}" 1.177 + 1.178 +while true; do 1.179 + su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"' 1.180 + su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"' 1.181 + sleep 5 1.182 +done</code></pre> 1.183 +<p>This file must be marked as executable:</p> 1.184 +<pre><code>chmod +x /opt/liquid_feedback_core/lf_updated</code></pre> 1.185 +<p>And this file should be started automatically at system boot.</p> 1.186 +<h2 id="setup-notification-loop-in-background">11. Setup notification loop in background</h2> 1.187 +<p>In addition to regular execution of <code>lf_update</code> and <code>lf_update_suggestion_order</code>, the following commands should be executed in background:</p> 1.188 +<pre><code>su - www-data 1.189 +cd /opt/liquid_feedback_frontend/ 1.190 +echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig</code></pre> 1.191 +<h2 id="start-the-sytem">12. Start the sytem</h2> 1.192 +<p>After <code>lf_update</code> 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.</p> 1.193 +</body> 1.194 +</html>