liquid_feedback_frontend

annotate INSTALL.html @ 1105:1b4bda1107b9

find changesets by author, revision, files, or words in the commit message
Fixed error when showing area before area member count is calculated first time
author bsw
date Mon Nov 10 17:35:48 2014 +0100 (2014-11-10)
parents 53b0139ed930
children 08adef9f05b9
rev   line source
bsw@1045 1 <html>
bsw@1045 2 <head>
jbe@1046 3 <title>LiquidFeedback Installation Instructions</title>
bsw@1045 4 </head>
bsw@1045 5 <body>
jbe@1046 6 <h1>LiquidFeedback Installation Instructions</h1>
jbe@1046 7
jbe@1046 8 <p>This document gives a short outline about the necessary steps to setup a
jbe@1046 9 LiquidFeedback system.</p>
jbe@1046 10
jbe@1046 11 <h2>1. Install necessary dependencies</h2>
jbe@1046 12
jbe@1046 13 <p>If you're using a Debian system, make sure that the following packages are
jbe@1046 14 installed:</p>
jbe@1046 15
bsw@1045 16 <ul>
bsw@1045 17 <li>lua5.1</li>
bsw@1045 18 <li>postgresql</li>
bsw@1045 19 <li>build-essential</li>
bsw@1045 20 <li>libpq-dev</li>
bsw@1045 21 <li>liblua5.1-0-dev</li>
bsw@1045 22 <li>lighttpd</li>
bsw@1045 23 <li>ghc</li>
bsw@1045 24 <li>libghc6-parsec3-dev</li>
bsw@1045 25 <li>imagemagick</li>
bsw@1045 26 <li>exim4</li>
jbe@1046 27 <li>markdown2 (install with Python's pip)</li>
bsw@1045 28 </ul>
jbe@1046 29
jbe@1046 30 <p>If you're using any other Linux distribution or BSD system, install the
jbe@1046 31 necessary software components accordingly.</p>
jbe@1046 32
jbe@1046 33 <h2>2. Ensure that the user account of your webserver has access to the database</h2>
jbe@1046 34
jbe@1046 35 <p>Whichever useraccount is used by the webserver (usually <code>www-data</code>) needs to
jbe@1046 36 have access to your PostgreSQL installation. This is done by executing
jbe@1046 37 PostgreSQL's shell command <code>createuser</code> as database superuser (usually <code>pgsql</code>,
jbe@1046 38 or <code>postgres</code> for Debian installations):</p>
jbe@1046 39
bsw@1045 40 <pre><code>su - postgres
bsw@1045 41 createuser
bsw@1045 42
bsw@1045 43 Enter name of role to add: www-data
bsw@1045 44 Shall the new role be a superuser? (y/n) n
bsw@1045 45 Shall the new role be allowed to create databases? (y/n) y
bsw@1045 46 Shall the new role be allowed to create more new roles? (y/n) n
bsw@1045 47
jbe@1046 48 exit
jbe@1046 49 </code></pre>
jbe@1046 50
jbe@1046 51 <h2>3. Install and configure LiquidFeedback-Core</h2>
jbe@1046 52
jbe@1046 53 <p>We recommend to create the database with the same user as your webserver
jbe@1046 54 (usually <code>www-data</code>) to avoid having to setup database privileges.</p>
jbe@1046 55
jbe@1046 56 <p>The example below installs the database as <code>www-data</code> and stores the two
jbe@1046 57 executables <code>lf_update</code> and <code>lf_update_issue_order</code> in the directory
jbe@1046 58 <code>/opt/liquid_feedback_core/</code>:</p>
jbe@1046 59
bsw@1045 60 <pre><code># Download and unpack LiquidFeedback-Core
bsw@1045 61 # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
bsw@1045 62 make
bsw@1045 63 mkdir /opt/liquid_feedback_core
bsw@1045 64 cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core
bsw@1045 65 su - www-data
bsw@1045 66 cd /opt/liquid_feedback_core
bsw@1045 67 createdb liquid_feedback
bsw@1045 68 createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version
jbe@1046 69 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
jbe@1046 70 </code></pre>
jbe@1046 71
bsw@1045 72 <p>A simple configuration may look as follows:</p>
jbe@1046 73
bsw@1045 74 <pre><code>psql liquid_feedback
bsw@1045 75
jbe@1046 76 INSERT INTO system_setting (member_ttl) VALUES ('1 year');
jbe@1046 77 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
jbe@1046 78 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
jbe@1046 79 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
jbe@1046 80 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
jbe@1046 81 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 82 INSERT INTO unit (name) VALUES ('Our organization');
jbe@1046 83 INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
jbe@1046 84 INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
jbe@1046 85 </code></pre>
jbe@1046 86
bsw@1045 87 <p>If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:</p>
jbe@1046 88
jbe@1046 89 <pre><code>INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
jbe@1046 90 </code></pre>
jbe@1046 91
bsw@1045 92 <p>Exit the <code>psql</code> interface by typing:</p>
jbe@1046 93
jbe@1046 94 <pre><code>\q
jbe@1046 95 </code></pre>
jbe@1046 96
bsw@1045 97 <p>And don't forget to quit the <code>www-data</code> shell:</p>
jbe@1046 98
jbe@1046 99 <pre><code>exit
jbe@1046 100 </code></pre>
jbe@1046 101
jbe@1046 102 <h2>4. Install WebMCP</h2>
jbe@1046 103
jbe@1046 104 <p>Note: Using Debian, it may be necessary to append <code>-I /usr/include/lua5.1</code> at
jbe@1046 105 the end of the CFLAGS line in <code>Makefile.options</code> of the WebMCP source
jbe@1046 106 distibution:</p>
jbe@1046 107
bsw@1045 108 <pre><code># Download and unpack WebMCP
bsw@1045 109 # from http://www.public-software-group.org/pub/projects/webmcp/
bsw@1045 110 vi Makefile.options # Debian requires -I /usr/include/lua5.1 at end of CFLAGS line
bsw@1045 111 make
bsw@1045 112 mkdir /opt/webmcp
jbe@1046 113 cp -RL framework/* /opt/webmcp/
jbe@1046 114 </code></pre>
bsw@1045 115
jbe@1046 116 <h2>5. Install the LiquidFeedback-Frontend</h2>
bsw@1045 117
bsw@1045 118 <p>Unpack source tree into appropriate directory, e.g. <code>/opt/liquid_feedback_frontend</code>:</p>
jbe@1046 119
bsw@1045 120 <pre><code># Download LiquidFeedback-Frontend
bsw@1045 121 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
jbe@1046 122 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
jbe@1046 123 </code></pre>
jbe@1046 124
bsw@1045 125 <p>Create HTML code for help texts:</p>
jbe@1046 126
bsw@1045 127 <pre><code>cd /opt/liquid_feedback_frontend/locale
jbe@1046 128 PATH=/opt/rocketwiki-lqfb:$PATH make
jbe@1046 129 </code></pre>
jbe@1046 130
bsw@1045 131 <p>Make <code>tmp/</code> directory of LiquidFeedback-Frontend writable for webserver:</p>
jbe@1046 132
jbe@1046 133 <pre><code>chown www-data /opt/liquid_feedback_frontend/tmp
jbe@1046 134 </code></pre>
jbe@1046 135
bsw@1045 136 <p>Compile binary for fast delivery of member images:</p>
jbe@1046 137
bsw@1045 138 <pre><code>cd /opt/liquid_feedback_frontend/fastpath
bsw@1045 139 vi getpic.c # check and modify #define commands as necessary
jbe@1046 140 make
jbe@1046 141 </code></pre>
jbe@1046 142
jbe@1046 143 <h2>6. Configure mail system</h2>
jbe@1046 144
jbe@1046 145 <p>It may be necessary to configure your server's mail system, e.g. running
jbe@1046 146 <code>dpkg-reconfigure exim4-config</code> on a Debian system.</p>
jbe@1046 147
jbe@1046 148 <h2>7. Configure the Webserver for LiquidFeedback:</h2>
jbe@1046 149
jbe@1046 150 <p>A sample configuration for <code>lighttpd</code> is given below (assuming <code>mod_alias</code> has
jbe@1046 151 been included elsewhere):</p>
jbe@1046 152
jbe@1046 153 <pre><code>server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")
bsw@1045 154
bsw@1045 155 # Enable CGI-Execution of *.lua files through lua binary
jbe@1046 156 cgi.assign += ( ".lua" =&gt; "/usr/bin/lua5.1" )
bsw@1045 157
jbe@1046 158 alias.url += ( "/lf/fastpath/" =&gt; "/opt/liquid_feedback_frontend/fastpath/",
jbe@1046 159 "/lf/static" =&gt; "/opt/liquid_feedback_frontend/static",
jbe@1046 160 "/lf" =&gt; "/opt/webmcp/cgi-bin" )
bsw@1045 161
bsw@1045 162 # Configure environment for demo application
jbe@1046 163 $HTTP["url"] =~ "^/lf" {
bsw@1045 164 setenv.add-environment += (
jbe@1046 165 "LANG" =&gt; "en_US.UTF-8",
jbe@1046 166 "WEBMCP_APP_BASEPATH" =&gt; "/opt/liquid_feedback_frontend/",
jbe@1046 167 "WEBMCP_CONFIG_NAME" =&gt; "myconfig")
bsw@1045 168 }
bsw@1045 169
bsw@1045 170 # URL beautification
bsw@1045 171 url.rewrite-once += (
bsw@1045 172 # do not rewrite static URLs
jbe@1046 173 "^/lf/fastpath/(.*)$" =&gt; "/lf/fastpath/$1",
jbe@1046 174 "^/lf/static/(.*)$" =&gt; "/lf/static/$1",
bsw@1045 175
bsw@1045 176 # dynamic URLs
jbe@1046 177 "^/lf/([^\?]*)(\?(.*))?$" =&gt; "/lf/webmcp-wrapper.lua?_webmcp_path=$1&amp;$3",
bsw@1045 178
bsw@1045 179 )
bsw@1045 180
jbe@1046 181 $HTTP["url"] =~ "^/lf/fastpath/" {
jbe@1046 182 cgi.assign = ( "" =&gt; "" )
jbe@1046 183 setenv.add-response-header = ( "Cache-Control" =&gt; "private; max-age=86400" )
jbe@1046 184 }
jbe@1046 185 </code></pre>
jbe@1046 186
jbe@1046 187 <p>If you're using Debian, you may want to create a file with the name
jbe@1046 188 <code>/etc/lighttpd/conf-available/60-liquidfeedback.conf</code> and create a softlink in
jbe@1046 189 <code>/etc/lighttpd/conf-enabled/</code>.</p>
jbe@1046 190
jbe@1046 191 <h2>8. Configure the LiquidFeedback-Frontend:</h2>
jbe@1046 192
bsw@1045 193 <pre><code>cd /opt/liquid_feedback_frontend/config
bsw@1045 194 cp example.lua myconfig.lua
jbe@1046 195 # edit myconfig.lua according to your needs
jbe@1046 196 </code></pre>
jbe@1046 197
jbe@1046 198 <p>Use the following option in your configuration file to enable fast image
jbe@1046 199 loading:</p>
jbe@1046 200
bsw@1045 201 <pre><code>config.fastpath_url_func = function(member_id, image_type)
jbe@1046 202 return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)
jbe@1046 203 end
jbe@1046 204 </code></pre>
jbe@1046 205
jbe@1051 206 <h2>9. Setup regular execution of <code>lf_update</code> and related commands </h2>
jbe@1046 207
jbe@1051 208 <p>The executables <code>lf_update</code>, <code>lf_update_issue_order</code>, and
jbe@1051 209 <code>lf_update_suggestion_order</code> must be executed regularly. This may be achieved
jbe@1051 210 by creating a file named <code>/opt/liquid_feedback_core/lf_updated</code> with the
jbe@1051 211 following contents:</p>
jbe@1046 212
bsw@1045 213 <pre><code>#!/bin/sh
bsw@1045 214
jbe@1046 215 PIDFILE="/var/run/lf_updated.pid"
bsw@1045 216 PID=$$
bsw@1045 217
jbe@1046 218 if [ -f "${PIDFILE}" ] &amp;&amp; kill -CONT $( cat "${PIDFILE}" ); then
jbe@1046 219 echo "lf_updated is already running."
bsw@1045 220 exit 1
bsw@1045 221 fi
bsw@1045 222
jbe@1046 223 echo "${PID}" &gt; "${PIDFILE}"
bsw@1045 224
bsw@1045 225 while true; do
jbe@1046 226 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2&gt;&amp;1 | logger -t "lf_updated"'
jbe@1051 227 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2&gt;&amp;1 | logger -t "lf_updated"'
jbe@1046 228 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2&gt;&amp;1 | logger -t "lf_updated"'
bsw@1045 229 sleep 5
jbe@1046 230 done
jbe@1046 231 </code></pre>
jbe@1046 232
bsw@1045 233 <p>This file must be marked as executable:</p>
jbe@1046 234
jbe@1046 235 <pre><code>chmod +x /opt/liquid_feedback_core/lf_updated
jbe@1046 236 </code></pre>
jbe@1046 237
bsw@1045 238 <p>And this file should be started automatically at system boot.</p>
jbe@1046 239
jbe@1046 240 <h2>10. Setup notification loop in background</h2>
jbe@1046 241
jbe@1046 242 <p>In addition to regular execution of <code>lf_update</code> and
jbe@1046 243 <code>lf_update_suggestion_order</code>, the following commands should be executed in
jbe@1046 244 background:</p>
jbe@1046 245
bsw@1045 246 <pre><code>su - www-data
bsw@1045 247 cd /opt/liquid_feedback_frontend/
jbe@1046 248 echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig
jbe@1046 249 </code></pre>
jbe@1046 250
jbe@1046 251 <h2>11. Start the sytem</h2>
jbe@1046 252
jbe@1046 253 <p>After <code>lf_update</code> has been executed at least once, and the webserver has been
jbe@1046 254 restarted (using the configuration above), you should be able to access your
jbe@1046 255 LiquidFeedback system.</p>
bsw@1045 256 </body>
bsw@1045 257 </html>

Impressum / About Us