liquid_feedback_frontend

annotate INSTALL.mkd @ 1045:701a5cf6b067

find changesets by author, revision, files, or words in the commit message
Imported LiquidFeedback Frontend 3.0 branch
author bsw
date Thu Jul 10 01:19:48 2014 +0200 (2014-07-10)
parents
children b9300c2e75da
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
bsw@1045 14 * lua5.1
bsw@1045 15 * postgresql
bsw@1045 16 * build-essential
bsw@1045 17 * libpq-dev
bsw@1045 18 * liblua5.1-0-dev
bsw@1045 19 * lighttpd
bsw@1045 20 * ghc
bsw@1045 21 * libghc6-parsec3-dev
bsw@1045 22 * imagemagick
bsw@1045 23 * exim4
bsw@1045 24
bsw@1045 25 If you're using any other Linux distribution or BSD system, install the
bsw@1045 26 necessary software components accordingly.
bsw@1045 27
bsw@1045 28
bsw@1045 29 2. Ensure that the user account of your webserver has access to the database
bsw@1045 30 ----------------------------------------------------------------------------
bsw@1045 31
bsw@1045 32 Whichever useraccount is used by the webserver (usually `www-data`) needs to
bsw@1045 33 have access to your PostgreSQL installation. This is done by executing
bsw@1045 34 PostgreSQL's shell command `createuser` as database superuser (usually `pgsql`,
bsw@1045 35 or `postgres` for Debian installations):
bsw@1045 36
bsw@1045 37 su - postgres
bsw@1045 38 createuser
bsw@1045 39
bsw@1045 40 Enter name of role to add: www-data
bsw@1045 41 Shall the new role be a superuser? (y/n) n
bsw@1045 42 Shall the new role be allowed to create databases? (y/n) y
bsw@1045 43 Shall the new role be allowed to create more new roles? (y/n) n
bsw@1045 44
bsw@1045 45 exit
bsw@1045 46
bsw@1045 47
bsw@1045 48 3. Install and configure LiquidFeedback-Core
bsw@1045 49 --------------------------------------------
bsw@1045 50
bsw@1045 51 We recommend to create the database with the same user as your webserver
bsw@1045 52 (usually `www-data`) to avoid having to setup database privileges.
bsw@1045 53
bsw@1045 54 The example below installs the database as `www-data` and stores the two
bsw@1045 55 executables `lf_update` and `lf_update_issue_order` in the directory
bsw@1045 56 `/opt/liquid_feedback_core/`:
bsw@1045 57
bsw@1045 58 # Download and unpack LiquidFeedback-Core
bsw@1045 59 # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
bsw@1045 60 make
bsw@1045 61 mkdir /opt/liquid_feedback_core
bsw@1045 62 cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core
bsw@1045 63 su - www-data
bsw@1045 64 cd /opt/liquid_feedback_core
bsw@1045 65 createdb liquid_feedback
bsw@1045 66 createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version
bsw@1045 67 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
bsw@1045 68
bsw@1045 69 A simple configuration may look as follows:
bsw@1045 70
bsw@1045 71 psql liquid_feedback
bsw@1045 72
bsw@1045 73 INSERT INTO system_setting (member_ttl) VALUES ('1 year');
bsw@1045 74 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
bsw@1045 75 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
bsw@1045 76 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
bsw@1045 77 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
bsw@1045 78 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 79 INSERT INTO unit (name) VALUES ('Our organization');
bsw@1045 80 INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
bsw@1045 81 INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
bsw@1045 82
bsw@1045 83 If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:
bsw@1045 84
bsw@1045 85 INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
bsw@1045 86
bsw@1045 87 Exit the `psql` interface by typing:
bsw@1045 88
bsw@1045 89 \q
bsw@1045 90
bsw@1045 91 And don't forget to quit the `www-data` shell:
bsw@1045 92
bsw@1045 93 exit
bsw@1045 94
bsw@1045 95
bsw@1045 96 4. Install WebMCP
bsw@1045 97 -----------------
bsw@1045 98
bsw@1045 99 Note: Using Debian, it may be necessary to append `-I /usr/include/lua5.1` at
bsw@1045 100 the end of the CFLAGS line in `Makefile.options` of the WebMCP source
bsw@1045 101 distibution:
bsw@1045 102
bsw@1045 103 # Download and unpack WebMCP
bsw@1045 104 # from http://www.public-software-group.org/pub/projects/webmcp/
bsw@1045 105 vi Makefile.options # Debian requires -I /usr/include/lua5.1 at end of CFLAGS line
bsw@1045 106 make
bsw@1045 107 mkdir /opt/webmcp
bsw@1045 108 cp -RL framework/* /opt/webmcp/
bsw@1045 109
bsw@1045 110
bsw@1045 111 5. Install RocketWiki LqFb-Edition
bsw@1045 112 ----------------------------------
bsw@1045 113
bsw@1045 114 # Download and unpack "RocketWiki LqFb-Edition"
bsw@1045 115 # from http://www.public-software-group.org/pub/projects/rocketwiki/liquid_feedback_edition/
bsw@1045 116 make
bsw@1045 117 mkdir /opt/rocketwiki-lqfb
bsw@1045 118 cp rocketwiki-lqfb rocketwiki-lqfb-compat /opt/rocketwiki-lqfb/
bsw@1045 119
bsw@1045 120 If you experience problems with multi-byte encoding (UTF-8) later, then apply
bsw@1045 121 the following patch to both `rocketwiki-lqfb.hs` and
bsw@1045 122 `rocketwiki-lqfb-compat.hs` prior compilation:
bsw@1045 123
bsw@1045 124 --- rocketwiki-lqfb.hs
bsw@1045 125 +++ rocketwiki-lqfb.hs
bsw@1045 126 @@ -1,4 +1,6 @@
bsw@1045 127
bsw@1045 128 +import System.IO (hSetEncoding, stdin, stdout, utf8)
bsw@1045 129 +
bsw@1045 130 import Text.ParserCombinators.Parsec
bsw@1045 131 import Control.Applicative ((<$>), (<*>))
bsw@1045 132 import Data.List (intercalate)
bsw@1045 133 @@ -405,7 +407,10 @@
bsw@1045 134 return htmlEntity
bsw@1045 135
bsw@1045 136
bsw@1045 137 -main = interact wikiParse
bsw@1045 138 +main = do
bsw@1045 139 + hSetEncoding stdin utf8
bsw@1045 140 + hSetEncoding stdout utf8
bsw@1045 141 + interact wikiParse
bsw@1045 142
bsw@1045 143 wikiParse str
bsw@1045 144 | success parseResult = html
bsw@1045 145
bsw@1045 146
bsw@1045 147 6. Install the LiquidFeedback-Frontend
bsw@1045 148 --------------------------------------
bsw@1045 149
bsw@1045 150 Unpack source tree into appropriate directory, e.g. `/opt/liquid_feedback_frontend`:
bsw@1045 151
bsw@1045 152 # Download LiquidFeedback-Frontend
bsw@1045 153 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
bsw@1045 154 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
bsw@1045 155
bsw@1045 156 Create HTML code for help texts:
bsw@1045 157
bsw@1045 158 cd /opt/liquid_feedback_frontend/locale
bsw@1045 159 PATH=/opt/rocketwiki-lqfb:$PATH make
bsw@1045 160
bsw@1045 161 Make `tmp/` directory of LiquidFeedback-Frontend writable for webserver:
bsw@1045 162
bsw@1045 163 chown www-data /opt/liquid_feedback_frontend/tmp
bsw@1045 164
bsw@1045 165 Compile binary for fast delivery of member images:
bsw@1045 166
bsw@1045 167 cd /opt/liquid_feedback_frontend/fastpath
bsw@1045 168 vi getpic.c # check and modify #define commands as necessary
bsw@1045 169 make
bsw@1045 170
bsw@1045 171
bsw@1045 172 7. Configure mail system
bsw@1045 173 ------------------------
bsw@1045 174
bsw@1045 175 It may be necessary to configure your server's mail system, e.g. running
bsw@1045 176 `dpkg-reconfigure exim4-config` on a Debian system.
bsw@1045 177
bsw@1045 178
bsw@1045 179 8. Configure the Webserver for LiquidFeedback:
bsw@1045 180 ----------------------------------------------
bsw@1045 181
bsw@1045 182 A sample configuration for `lighttpd` is given below (assuming `mod_alias` has
bsw@1045 183 been included elsewhere):
bsw@1045 184
bsw@1045 185 server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")
bsw@1045 186
bsw@1045 187 # Enable CGI-Execution of *.lua files through lua binary
bsw@1045 188 cgi.assign += ( ".lua" => "/usr/bin/lua5.1" )
bsw@1045 189
bsw@1045 190 alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/",
bsw@1045 191 "/lf/static" => "/opt/liquid_feedback_frontend/static",
bsw@1045 192 "/lf" => "/opt/webmcp/cgi-bin" )
bsw@1045 193
bsw@1045 194 # Configure environment for demo application
bsw@1045 195 $HTTP["url"] =~ "^/lf" {
bsw@1045 196 setenv.add-environment += (
bsw@1045 197 "LANG" => "en_US.UTF-8",
bsw@1045 198 "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/",
bsw@1045 199 "WEBMCP_CONFIG_NAME" => "myconfig")
bsw@1045 200 }
bsw@1045 201
bsw@1045 202 # URL beautification
bsw@1045 203 url.rewrite-once += (
bsw@1045 204 # do not rewrite static URLs
bsw@1045 205 "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1",
bsw@1045 206 "^/lf/static/(.*)$" => "/lf/static/$1",
bsw@1045 207
bsw@1045 208 # dynamic URLs
bsw@1045 209 "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3",
bsw@1045 210
bsw@1045 211 )
bsw@1045 212
bsw@1045 213 $HTTP["url"] =~ "^/lf/fastpath/" {
bsw@1045 214 cgi.assign = ( "" => "" )
bsw@1045 215 setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" )
bsw@1045 216 }
bsw@1045 217
bsw@1045 218 If you're using Debian, you may want to create a file with the name
bsw@1045 219 `/etc/lighttpd/conf-available/60-liquidfeedback.conf` and create a softlink in
bsw@1045 220 `/etc/lighttpd/conf-enabled/`.
bsw@1045 221
bsw@1045 222
bsw@1045 223 9. Configure the LiquidFeedback-Frontend:
bsw@1045 224 -----------------------------------------
bsw@1045 225
bsw@1045 226 cd /opt/liquid_feedback_frontend/config
bsw@1045 227 cp example.lua myconfig.lua
bsw@1045 228 # edit myconfig.lua according to your needs
bsw@1045 229
bsw@1045 230 Use the following option in your configuration file to enable fast image
bsw@1045 231 loading:
bsw@1045 232
bsw@1045 233 config.fastpath_url_func = function(member_id, image_type)
bsw@1045 234 return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)
bsw@1045 235 end
bsw@1045 236
bsw@1045 237
bsw@1045 238 10. Setup regular execution of `lf_update` and `lf_update_suggestion_order`
bsw@1045 239 ---------------------------------------------------------------------------
bsw@1045 240
bsw@1045 241 The executables `lf_update` and `lf_update_suggestion_order` must be executed
bsw@1045 242 regularly. This may be achieved by creating a file named
bsw@1045 243 `/opt/liquid_feedback_core/lf_updated` with the following contents:
bsw@1045 244
bsw@1045 245 #!/bin/sh
bsw@1045 246
bsw@1045 247 PIDFILE="/var/run/lf_updated.pid"
bsw@1045 248 PID=$$
bsw@1045 249
bsw@1045 250 if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then
bsw@1045 251 echo "lf_updated is already running."
bsw@1045 252 exit 1
bsw@1045 253 fi
bsw@1045 254
bsw@1045 255 echo "${PID}" > "${PIDFILE}"
bsw@1045 256
bsw@1045 257 while true; do
bsw@1045 258 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
bsw@1045 259 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
bsw@1045 260 sleep 5
bsw@1045 261 done
bsw@1045 262
bsw@1045 263 This file must be marked as executable:
bsw@1045 264
bsw@1045 265 chmod +x /opt/liquid_feedback_core/lf_updated
bsw@1045 266
bsw@1045 267 And this file should be started automatically at system boot.
bsw@1045 268
bsw@1045 269
bsw@1045 270 11. Setup notification loop in background
bsw@1045 271 -----------------------------------------
bsw@1045 272
bsw@1045 273 In addition to regular execution of `lf_update` and
bsw@1045 274 `lf_update_suggestion_order`, the following commands should be executed in
bsw@1045 275 background:
bsw@1045 276
bsw@1045 277 su - www-data
bsw@1045 278 cd /opt/liquid_feedback_frontend/
bsw@1045 279 echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig
bsw@1045 280
bsw@1045 281
bsw@1045 282 12. Start the sytem
bsw@1045 283 -------------------
bsw@1045 284
bsw@1045 285 After `lf_update` has been executed at least once, and the webserver has been
bsw@1045 286 restarted (using the configuration above), you should be able to access your
bsw@1045 287 LiquidFeedback system.
bsw@1045 288
bsw@1045 289

Impressum / About Us