liquid_feedback_frontend

annotate INSTALL.mkd @ 1244:ae9812d9f653

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

Impressum / About Us