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