liquid_feedback_frontend
view INSTALL.html @ 1196:5f9cf5a1d12f
Added missing "lf_update_suggestion_order" file to "cp" command in INSTALL.mkd and INSTALL.html
| author | jbe |
|---|---|
| date | Mon Jun 01 15:11:32 2015 +0200 (2015-06-01) |
| parents | bf158c59f827 |
| children | ae9812d9f653 |
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 (<code>apt-get install python-pip; pip install markdown2</code>)</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 -s $SHELL
40 createuser --no-superuser --createdb --no-createrole www-data
41 exit
42 </code></pre>
44 <h2>3. Install and configure LiquidFeedback-Core</h2>
46 <p>We recommend to create the database with the same user as your webserver
47 (usually <code>www-data</code>) to avoid having to setup database privileges.</p>
49 <p>The example below installs the database as <code>www-data</code> and stores the two
50 executables <code>lf_update</code> and <code>lf_update_issue_order</code> in the directory
51 <code>/opt/liquid_feedback_core/</code>:</p>
53 <pre><code># Download and unpack LiquidFeedback-Core
54 # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
55 make
56 mkdir /opt/liquid_feedback_core
57 cp core.sql lf_update lf_update_issue_order lf_update_suggestion_order /opt/liquid_feedback_core
58 su www-data -s $SHELL
59 cd /opt/liquid_feedback_core
60 createdb liquid_feedback
61 createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version
62 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
63 </code></pre>
65 <p>A simple configuration may look as follows:</p>
67 <pre><code>psql liquid_feedback
69 INSERT INTO system_setting (member_ttl) VALUES ('1 year');
70 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
71 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
72 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
73 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
74 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);
75 INSERT INTO unit (name) VALUES ('Our organization');
76 INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
77 INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
78 </code></pre>
80 <p>If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:</p>
82 <pre><code>INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
83 </code></pre>
85 <p>Exit the <code>psql</code> interface by typing:</p>
87 <pre><code>\q
88 </code></pre>
90 <p>And don't forget to quit the <code>www-data</code> shell:</p>
92 <pre><code>exit
93 </code></pre>
95 <h2>4. Install Moonbridge (only for WebMCP 2.x)</h2>
97 <pre><code># Download and unpack Moonbridge
98 # from http://www.public-software-group.org/pub/projects/moonbridge/
99 pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua
100 mkdir /opt/moonbridge
101 cp moonbridge /opt/moonbridge/
102 cp moonbridge_http.lua /opt/moonbridge/
103 </code></pre>
105 <h2>5. Install WebMCP</h2>
107 <p>Note: Using Debian, it may be necessary to append <code>-I /usr/include/lua5.2</code> at
108 the end of the CFLAGS line in <code>Makefile.options</code> of the WebMCP source
109 distibution:</p>
111 <pre><code># Download and unpack WebMCP
112 # from http://www.public-software-group.org/pub/projects/webmcp/
113 vi Makefile.options # Debian requires -I /usr/include/lua5.2 at end of CFLAGS line
114 make
115 mkdir /opt/webmcp
116 cp -RL framework/* /opt/webmcp/
117 </code></pre>
119 <h2>6. Install the LiquidFeedback-Frontend</h2>
121 <p>Unpack source tree into appropriate directory, e.g. <code>/opt/liquid_feedback_frontend</code>:</p>
123 <pre><code># Download LiquidFeedback-Frontend
124 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
125 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
126 </code></pre>
128 <p>Make <code>tmp/</code> directory of LiquidFeedback-Frontend writable for webserver:</p>
130 <pre><code>chown www-data /opt/liquid_feedback_frontend/tmp
131 </code></pre>
133 <p>Compile binary for fast delivery of member images (only necessary for WebMCP 1.2.x):</p>
135 <pre><code>cd /opt/liquid_feedback_frontend/fastpath
136 vi getpic.c # check and modify #define commands as necessary
137 make
138 </code></pre>
140 <h2>7. Configure mail system</h2>
142 <p>It may be necessary to configure your server's mail system, e.g. running
143 <code>dpkg-reconfigure exim4-config</code> on a Debian system.</p>
145 <h2>8. Configure the Webserver for LiquidFeedback (only for WebMCP 1.2.x)</h2>
147 <p>A sample configuration for <code>lighttpd</code> is given below (assuming <code>mod_alias</code> has
148 been included elsewhere):</p>
150 <pre><code>server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")
152 # Enable CGI-Execution of *.lua files through lua binary
153 cgi.assign += ( ".lua" => "/usr/bin/lua5.1" )
155 alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/",
156 "/lf/static" => "/opt/liquid_feedback_frontend/static",
157 "/lf" => "/opt/webmcp/cgi-bin" )
159 # Configure environment for demo application
160 $HTTP["url"] =~ "^/lf" {
161 setenv.add-environment += (
162 "LANG" => "en_US.UTF-8",
163 "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/",
164 "WEBMCP_CONFIG_NAME" => "myconfig")
165 }
167 # URL beautification
168 url.rewrite-once += (
169 # do not rewrite static URLs
170 "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1",
171 "^/lf/static/(.*)$" => "/lf/static/$1",
173 # dynamic URLs
174 "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3",
176 )
178 $HTTP["url"] =~ "^/lf/fastpath/" {
179 cgi.assign = ( "" => "" )
180 setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" )
181 }
182 </code></pre>
184 <p>If you're using Debian, you may want to create a file with the name
185 <code>/etc/lighttpd/conf-available/60-liquidfeedback.conf</code> and create a softlink in
186 <code>/etc/lighttpd/conf-enabled/</code>.</p>
188 <h2>9. Configure the LiquidFeedback-Frontend</h2>
190 <pre><code>cd /opt/liquid_feedback_frontend/config
191 cp example.lua myconfig.lua
192 # edit myconfig.lua according to your needs
193 </code></pre>
195 <p>Use the following option in your configuration file to enable fast image
196 loading (only for WebMCP 1.2.x):</p>
198 <pre><code>config.fastpath_url_func = function(member_id, image_type)
199 return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)
200 end
201 </code></pre>
203 <h2>10. Setup regular execution of <code>lf_update</code> and related commands </h2>
205 <p>The executables <code>lf_update</code>, <code>lf_update_issue_order</code>, and
206 <code>lf_update_suggestion_order</code> must be executed regularly. This may be achieved
207 by creating a file named <code>/opt/liquid_feedback_core/lf_updated</code> with the
208 following contents:</p>
210 <pre><code>#!/bin/sh
212 PIDFILE="/var/run/lf_updated.pid"
213 PID=$$
215 if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then
216 echo "lf_updated is already running."
217 exit 1
218 fi
220 echo "${PID}" > "${PIDFILE}"
222 while true; do
223 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
224 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
225 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
226 sleep 5
227 done
228 </code></pre>
230 <p>This file must be marked as executable:</p>
232 <pre><code>chmod +x /opt/liquid_feedback_core/lf_updated
233 </code></pre>
235 <p>And this file should be started automatically at system boot.</p>
237 <h2>11. Setup notification loop in background (only for WebMCP 1.2.x)</h2>
239 <p>In addition to regular execution of <code>lf_update</code> and
240 <code>lf_update_suggestion_order</code>, the following commands should be executed in
241 background:</p>
243 <pre><code>su www-data -s $SHELL
244 cd /opt/liquid_feedback_frontend/
245 echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig
246 </code></pre>
248 <h2>12. Start the system</h2>
250 <p>After <code>lf_update</code> has been executed at least once and (in case of WebMCP 1.2.x)
251 the webserver has been restarted (using the configuration above), you should be
252 able to access your LiquidFeedback system.</p>
254 <p>If you use WebMCP 2.x, the server is started by calling:</p>
256 <pre><code>su www-data -s $SHELL
257 /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig
258 </code></pre>
260 <p>In the latter case, the Moonbridge server will open a TCP port according to
261 your configuration. Directly accessing this TCP port through your webbrowser
262 is helpful for development purposes. For real-life deployment, however, it is
263 recommended to further proxy the application (e.g. using nginx). The proxy can
264 also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge
265 itself).</p>
267 <p>To start the Moonbridge as a background process, please refer to the Moonbridge
268 command line options:</p>
270 <pre><code>Get this help message: moonbridge {-h|--help}
271 Usage: moonbridge \
272 [-b|--background] \
273 [-d|--debug] \
274 [-f|--logfacility {DAEMON|USER|0|1|...|7}] \
275 [-i|--logident <syslog ident> \
276 [-l|--logfile <logfile>] \
277 [-p|--pidfile <pidfile>] \
278 [-s|--stats] \
279 -- <Lua script> [<cmdline options for Lua script>]
280 </code></pre>
281 </body>
282 </html>