liquid_feedback_frontend
view INSTALL.html @ 1250:84f6e17c7ceb
Completed support for new notification system
| author | bsw |
|---|---|
| date | Sun Apr 17 15:03:44 2016 +0200 (2016-04-17) |
| parents | 78d3be54cfe0 |
| children | 7ea154c9238a |
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>pmake or bmake</li>
23 <li>imagemagick</li>
24 <li>exim4</li>
25 <li>markdown2 (<code>apt-get install python-pip; pip install markdown2</code>)</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 -s $SHELL
39 createuser --no-superuser --createdb --no-createrole www-data
40 exit
41 </code></pre>
43 <h2>3. Install and configure LiquidFeedback-Core</h2>
45 <p>We recommend to create the database with the same user as your webserver
46 (usually <code>www-data</code>) to avoid having to setup database privileges.</p>
48 <p>The example below installs the database as <code>www-data</code> and stores the two
49 executables <code>lf_update</code> and <code>lf_update_issue_order</code> in the directory
50 <code>/opt/liquid_feedback_core/</code>:</p>
52 <pre><code># Download and unpack LiquidFeedback-Core
53 # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
54 make
55 mkdir /opt/liquid_feedback_core
56 cp core.sql lf_update lf_update_issue_order lf_update_suggestion_order /opt/liquid_feedback_core
57 su www-data -s $SHELL
58 cd /opt/liquid_feedback_core
59 createdb liquid_feedback
60 createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version
61 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
62 </code></pre>
64 <p>A simple configuration may look as follows:</p>
66 <pre><code>psql liquid_feedback
68 INSERT INTO system_setting (member_ttl) VALUES ('1 year');
69 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
70 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
71 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
72 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
73 INSERT INTO policy (index, name, min_admission_time, max_admission_time, discussion_time, verification_time, voting_time, issue_quorum_num, issue_quorum_den, initiative_quorum_num, initiative_quorum_den) VALUES (1, 'Default policy', '4 days', '8 days', '15 days', '8 days', '15 days', 10, 100, 10, 100);
74 INSERT INTO unit (name) VALUES ('Our organization');
75 INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
76 INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
77 </code></pre>
79 <p>If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:</p>
81 <pre><code>INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
82 </code></pre>
84 <p>Exit the <code>psql</code> interface by typing:</p>
86 <pre><code>\q
87 </code></pre>
89 <p>And don't forget to quit the <code>www-data</code> shell:</p>
91 <pre><code>exit
92 </code></pre>
94 <h2>4. Install Moonbridge</h2>
96 <pre><code># Download and unpack Moonbridge
97 # from http://www.public-software-group.org/pub/projects/moonbridge/
98 pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua
99 mkdir /opt/moonbridge
100 cp moonbridge /opt/moonbridge/
101 cp moonbridge_http.lua /opt/moonbridge/
102 </code></pre>
104 <h2>5. Install WebMCP</h2>
106 <p>Note: Using Debian, it may be necessary to append <code>-I /usr/include/lua5.2</code> at
107 the end of the CFLAGS line in <code>Makefile.options</code> of the WebMCP source
108 distibution:</p>
110 <pre><code># Download and unpack WebMCP
111 # from http://www.public-software-group.org/pub/projects/webmcp/
112 vi Makefile.options # Debian requires -I /usr/include/lua5.2 at end of CFLAGS line
113 make
114 mkdir /opt/webmcp
115 cp -RL framework/* /opt/webmcp/
116 </code></pre>
118 <h2>6. Install the LiquidFeedback-Frontend</h2>
120 <p>Unpack source tree into appropriate directory, e.g. <code>/opt/liquid_feedback_frontend</code>:</p>
122 <pre><code># Download LiquidFeedback-Frontend
123 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
124 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
125 </code></pre>
127 <p>Make <code>tmp/</code> directory of LiquidFeedback-Frontend writable for webserver:</p>
129 <pre><code>chown www-data /opt/liquid_feedback_frontend/tmp
130 </code></pre>
132 <h2>7. Configure mail system</h2>
134 <p>It may be necessary to configure your server's mail system, e.g. running
135 <code>dpkg-reconfigure exim4-config</code> on a Debian system.</p>
137 <h2>8. Configure the LiquidFeedback-Frontend</h2>
139 <pre><code>cd /opt/liquid_feedback_frontend/config
140 cp example.lua myconfig.lua
141 # edit myconfig.lua according to your needs
142 </code></pre>
144 <h2>9. Setup regular execution of <code>lf_update</code> and related commands </h2>
146 <p>The executables <code>lf_update</code>, <code>lf_update_issue_order</code>, and
147 <code>lf_update_suggestion_order</code> must be executed regularly. This may be achieved
148 by creating a file named <code>/opt/liquid_feedback_core/lf_updated</code> with the
149 following contents:</p>
151 <pre><code>#!/bin/sh
153 PIDFILE="/var/run/lf_updated.pid"
154 PID=$$
156 if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then
157 echo "lf_updated is already running."
158 exit 1
159 fi
161 echo "${PID}" > "${PIDFILE}"
163 while true; do
164 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
165 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"'
166 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"'
167 sleep 5
168 done
169 </code></pre>
171 <p>This file must be marked as executable:</p>
173 <pre><code>chmod +x /opt/liquid_feedback_core/lf_updated
174 </code></pre>
176 <p>And this file should be started automatically at system boot.</p>
178 <h2>10. Start the system</h2>
180 <p>After <code>lf_update</code> has been executed at least once, you should be able to use
181 your LiquidFeedback system.</p>
183 <p>The server is started by calling:</p>
185 <pre><code>su www-data -s $SHELL
186 /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig
187 </code></pre>
189 <p>In the latter case, the Moonbridge server will open a TCP port according to
190 your configuration. Directly accessing this TCP port through your webbrowser
191 is helpful for development purposes. For real-life deployment, however, it is
192 recommended to further proxy the application (e.g. using nginx). The proxy can
193 also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge
194 itself).</p>
196 <p>To start the Moonbridge as a background process, please refer to the Moonbridge
197 command line options:</p>
199 <pre><code>Get this help message: moonbridge {-h|--help}
200 Usage: moonbridge \
201 [-b|--background] \
202 [-d|--debug] \
203 [-f|--logfacility {DAEMON|USER|0|1|...|7}] \
204 [-i|--logident <syslog ident> \
205 [-l|--logfile <logfile>] \
206 [-p|--pidfile <pidfile>] \
207 [-s|--stats] \
208 -- <Lua script> [<cmdline options for Lua script>]
209 </code></pre>
210 </body>
211 </html>