liquid_feedback_frontend

annotate INSTALL.html @ 1188:17b1456d0262

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

Impressum / About Us