liquid_feedback_frontend

annotate INSTALL.html @ 1525:628e1b9126c0

find changesets by author, revision, files, or words in the commit message
Handle no valid session in session filter correctly
author bsw
date Thu Aug 20 15:55:04 2020 +0200 (2020-08-20)
parents 7ea154c9238a
children 4d5f30d8df4a
rev   line source
bsw@1045 1 <html>
bsw@1045 2 <head>
jbe@1046 3 <title>LiquidFeedback Installation Instructions</title>
bsw@1045 4 </head>
bsw@1045 5 <body>
jbe@1046 6 <h1>LiquidFeedback Installation Instructions</h1>
jbe@1046 7
jbe@1046 8 <p>This document gives a short outline about the necessary steps to setup a
jbe@1046 9 LiquidFeedback system.</p>
jbe@1046 10
jbe@1046 11 <h2>1. Install necessary dependencies</h2>
jbe@1046 12
jbe@1046 13 <p>If you're using a Debian system, make sure that the following packages are
jbe@1046 14 installed:</p>
jbe@1046 15
bsw@1045 16 <ul>
jbe@1156 17 <li>build-essential</li>
jbe@1156 18 <li>lua5.2</li>
jbe@1156 19 <li>liblua5.2-dev</li>
jbe@1308 20 <li>postgresql (including the corresponding server-dev package)</li>
bsw@1045 21 <li>libpq-dev</li>
jbe@1308 22 <li>libbsd-dev</li>
jbe@1244 23 <li>pmake or bmake</li>
bsw@1045 24 <li>imagemagick</li>
bsw@1045 25 <li>exim4</li>
jbe@1191 26 <li>markdown2 (<code>apt-get install python-pip; pip install markdown2</code>)</li>
bsw@1045 27 </ul>
jbe@1046 28
jbe@1046 29 <p>If you're using any other Linux distribution or BSD system, install the
jbe@1046 30 necessary software components accordingly.</p>
jbe@1046 31
jbe@1046 32 <h2>2. Ensure that the user account of your webserver has access to the database</h2>
jbe@1046 33
jbe@1156 34 <p>The useraccount of the webserver (usually <code>www-data</code>) or the Moonbridge server
jbe@1156 35 process needs to have access to your PostgreSQL installation. This is done by
jbe@1156 36 executing PostgreSQL's shell command <code>createuser</code> as database superuser
jbe@1156 37 (usually <code>pgsql</code>, or <code>postgres</code> for Debian installations):</p>
jbe@1046 38
jbe@1191 39 <pre><code>su postgres -s $SHELL
jbe@1191 40 createuser --no-superuser --createdb --no-createrole www-data
jbe@1046 41 exit
jbe@1046 42 </code></pre>
jbe@1046 43
jbe@1046 44 <h2>3. Install and configure LiquidFeedback-Core</h2>
jbe@1046 45
jbe@1046 46 <p>We recommend to create the database with the same user as your webserver
jbe@1046 47 (usually <code>www-data</code>) to avoid having to setup database privileges.</p>
jbe@1046 48
jbe@1046 49 <p>The example below installs the database as <code>www-data</code> and stores the two
jbe@1046 50 executables <code>lf_update</code> and <code>lf_update_issue_order</code> in the directory
jbe@1046 51 <code>/opt/liquid_feedback_core/</code>:</p>
jbe@1046 52
bsw@1045 53 <pre><code># Download and unpack LiquidFeedback-Core
bsw@1045 54 # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
bsw@1045 55 make
bsw@1045 56 mkdir /opt/liquid_feedback_core
jbe@1196 57 cp core.sql lf_update lf_update_issue_order lf_update_suggestion_order /opt/liquid_feedback_core
jbe@1191 58 su www-data -s $SHELL
bsw@1045 59 cd /opt/liquid_feedback_core
bsw@1045 60 createdb liquid_feedback
bsw@1045 61 createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version
jbe@1046 62 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
jbe@1046 63 </code></pre>
jbe@1046 64
bsw@1045 65 <p>A simple configuration may look as follows:</p>
jbe@1046 66
bsw@1045 67 <pre><code>psql liquid_feedback
bsw@1045 68
jbe@1046 69 INSERT INTO system_setting (member_ttl) VALUES ('1 year');
jbe@1046 70 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
jbe@1046 71 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
jbe@1046 72 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
jbe@1046 73 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
jbe@1246 74 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);
jbe@1046 75 INSERT INTO unit (name) VALUES ('Our organization');
jbe@1046 76 INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
jbe@1046 77 INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
jbe@1046 78 </code></pre>
jbe@1046 79
bsw@1045 80 <p>If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:</p>
jbe@1046 81
jbe@1046 82 <pre><code>INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
jbe@1046 83 </code></pre>
jbe@1046 84
bsw@1045 85 <p>Exit the <code>psql</code> interface by typing:</p>
jbe@1046 86
jbe@1046 87 <pre><code>\q
jbe@1046 88 </code></pre>
jbe@1046 89
bsw@1045 90 <p>And don't forget to quit the <code>www-data</code> shell:</p>
jbe@1046 91
jbe@1046 92 <pre><code>exit
jbe@1046 93 </code></pre>
jbe@1046 94
jbe@1244 95 <h2>4. Install Moonbridge</h2>
jbe@1046 96
jbe@1156 97 <pre><code># Download and unpack Moonbridge
jbe@1156 98 # from http://www.public-software-group.org/pub/projects/moonbridge/
jbe@1156 99 pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua
jbe@1156 100 mkdir /opt/moonbridge
jbe@1156 101 cp moonbridge /opt/moonbridge/
jbe@1156 102 cp moonbridge_http.lua /opt/moonbridge/
jbe@1156 103 </code></pre>
jbe@1156 104
jbe@1156 105 <h2>5. Install WebMCP</h2>
jbe@1156 106
jbe@1156 107 <p>Note: Using Debian, it may be necessary to append <code>-I /usr/include/lua5.2</code> at
jbe@1046 108 the end of the CFLAGS line in <code>Makefile.options</code> of the WebMCP source
jbe@1046 109 distibution:</p>
jbe@1046 110
bsw@1045 111 <pre><code># Download and unpack WebMCP
bsw@1045 112 # from http://www.public-software-group.org/pub/projects/webmcp/
jbe@1156 113 vi Makefile.options # Debian requires -I /usr/include/lua5.2 at end of CFLAGS line
bsw@1045 114 make
bsw@1045 115 mkdir /opt/webmcp
jbe@1046 116 cp -RL framework/* /opt/webmcp/
jbe@1046 117 </code></pre>
bsw@1045 118
jbe@1156 119 <h2>6. Install the LiquidFeedback-Frontend</h2>
bsw@1045 120
bsw@1045 121 <p>Unpack source tree into appropriate directory, e.g. <code>/opt/liquid_feedback_frontend</code>:</p>
jbe@1046 122
bsw@1045 123 <pre><code># Download LiquidFeedback-Frontend
bsw@1045 124 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
jbe@1046 125 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
jbe@1046 126 </code></pre>
jbe@1046 127
bsw@1045 128 <p>Make <code>tmp/</code> directory of LiquidFeedback-Frontend writable for webserver:</p>
jbe@1046 129
jbe@1046 130 <pre><code>chown www-data /opt/liquid_feedback_frontend/tmp
jbe@1046 131 </code></pre>
jbe@1046 132
jbe@1156 133 <h2>7. Configure mail system</h2>
jbe@1046 134
jbe@1046 135 <p>It may be necessary to configure your server's mail system, e.g. running
jbe@1046 136 <code>dpkg-reconfigure exim4-config</code> on a Debian system.</p>
jbe@1046 137
jbe@1244 138 <h2>8. Configure the LiquidFeedback-Frontend</h2>
jbe@1046 139
bsw@1045 140 <pre><code>cd /opt/liquid_feedback_frontend/config
bsw@1045 141 cp example.lua myconfig.lua
jbe@1046 142 # edit myconfig.lua according to your needs
jbe@1046 143 </code></pre>
jbe@1046 144
jbe@1244 145 <h2>9. Setup regular execution of <code>lf_update</code> and related commands </h2>
jbe@1046 146
jbe@1051 147 <p>The executables <code>lf_update</code>, <code>lf_update_issue_order</code>, and
jbe@1051 148 <code>lf_update_suggestion_order</code> must be executed regularly. This may be achieved
jbe@1051 149 by creating a file named <code>/opt/liquid_feedback_core/lf_updated</code> with the
jbe@1051 150 following contents:</p>
jbe@1046 151
bsw@1045 152 <pre><code>#!/bin/sh
bsw@1045 153
jbe@1046 154 PIDFILE="/var/run/lf_updated.pid"
bsw@1045 155 PID=$$
bsw@1045 156
jbe@1046 157 if [ -f "${PIDFILE}" ] &amp;&amp; kill -CONT $( cat "${PIDFILE}" ); then
jbe@1046 158 echo "lf_updated is already running."
bsw@1045 159 exit 1
bsw@1045 160 fi
bsw@1045 161
jbe@1046 162 echo "${PID}" &gt; "${PIDFILE}"
bsw@1045 163
bsw@1045 164 while true; do
jbe@1191 165 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2&gt;&amp;1 | logger -t "lf_updated"'
jbe@1191 166 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2&gt;&amp;1 | logger -t "lf_updated"'
jbe@1191 167 su - www-data -s /bin/sh -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2&gt;&amp;1 | logger -t "lf_updated"'
bsw@1045 168 sleep 5
jbe@1046 169 done
jbe@1046 170 </code></pre>
jbe@1046 171
bsw@1045 172 <p>This file must be marked as executable:</p>
jbe@1046 173
jbe@1046 174 <pre><code>chmod +x /opt/liquid_feedback_core/lf_updated
jbe@1046 175 </code></pre>
jbe@1046 176
bsw@1045 177 <p>And this file should be started automatically at system boot.</p>
jbe@1046 178
jbe@1244 179 <h2>10. Start the system</h2>
jbe@1046 180
jbe@1244 181 <p>After <code>lf_update</code> has been executed at least once, you should be able to use
jbe@1244 182 your LiquidFeedback system.</p>
jbe@1046 183
jbe@1244 184 <p>The server is started by calling:</p>
jbe@1156 185
jbe@1192 186 <pre><code>su www-data -s $SHELL
jbe@1192 187 /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig
jbe@1156 188 </code></pre>
jbe@1162 189
jbe@1162 190 <p>In the latter case, the Moonbridge server will open a TCP port according to
jbe@1162 191 your configuration. Directly accessing this TCP port through your webbrowser
jbe@1162 192 is helpful for development purposes. For real-life deployment, however, it is
jbe@1162 193 recommended to further proxy the application (e.g. using nginx). The proxy can
jbe@1190 194 also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge
jbe@1190 195 itself).</p>
jbe@1190 196
jbe@1190 197 <p>To start the Moonbridge as a background process, please refer to the Moonbridge
jbe@1190 198 command line options:</p>
jbe@1190 199
jbe@1190 200 <pre><code>Get this help message: moonbridge {-h|--help}
jbe@1190 201 Usage: moonbridge \
jbe@1190 202 [-b|--background] \
jbe@1190 203 [-d|--debug] \
jbe@1190 204 [-f|--logfacility {DAEMON|USER|0|1|...|7}] \
jbe@1190 205 [-i|--logident &lt;syslog ident&gt; \
jbe@1190 206 [-l|--logfile &lt;logfile&gt;] \
jbe@1190 207 [-p|--pidfile &lt;pidfile&gt;] \
jbe@1190 208 [-s|--stats] \
jbe@1190 209 -- &lt;Lua script&gt; [&lt;cmdline options for Lua script&gt;]
jbe@1190 210 </code></pre>
bsw@1045 211 </body>
bsw@1045 212 </html>

Impressum / About Us