liquid_feedback_frontend
view INSTALL.html @ 1156:08adef9f05b9
Updated installation instructions for WebMCP 2.x
| author | jbe |
|---|---|
| date | Mon Mar 23 23:17:43 2015 +0100 (2015-03-23) |
| parents | 53b0139ed930 |
| children | a2922edacce0 |
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 the webserver has been
256 restarted (using the configuration above), you should be able to access your
257 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>
263 </body>
264 </html>