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