1 LiquidFeedback Installation Instructions

2 ========================================

3

4 This document gives a short outline about the necessary steps to setup a

5 LiquidFeedback system.

6

7

8 1. Install necessary dependencies

9 ---------------------------------

10

11 If you're using a Debian system, make sure that the following packages are

12 installed:

13

14 * build-essential

15 * lua5.2

16 * liblua5.2-dev

17 * postgresql

18 * libpq-dev

19 * lighttpd (only for WebMCP 1.2.x support)

20 * imagemagick

21 * exim4

22 * markdown2 (install with Python's pip)

23

24 If you're using any other Linux distribution or BSD system, install the

25 necessary software components accordingly.

26

27

28 2. Ensure that the user account of your webserver has access to the database

29 ----------------------------------------------------------------------------

30

31 The useraccount of the webserver (usually `www-data`) or the Moonbridge server

32 process needs to have access to your PostgreSQL installation. This is done by

33 executing PostgreSQL's shell command `createuser` as database superuser

34 (usually `pgsql`, or `postgres` for Debian installations):

35

36 su - postgres

37 createuser

38

39 Enter name of role to add: www-data

40 Shall the new role be a superuser? (y/n) n

41 Shall the new role be allowed to create databases? (y/n) y

42 Shall the new role be allowed to create more new roles? (y/n) n

43

44 exit

45

46

47 3. Install and configure LiquidFeedback-Core

48 --------------------------------------------

49

50 We recommend to create the database with the same user as your webserver

51 (usually `www-data`) to avoid having to setup database privileges.

52

53 The example below installs the database as `www-data` and stores the two

54 executables `lf_update` and `lf_update_issue_order` in the directory

55 `/opt/liquid_feedback_core/`:

56

57 # Download and unpack LiquidFeedback-Core

58 # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/

59 make

60 mkdir /opt/liquid_feedback_core

61 cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core

62 su - www-data

63 cd /opt/liquid_feedback_core

64 createdb liquid_feedback

65 createlang plpgsql liquid_feedback # command may be omitted, depending on PostgreSQL version

66 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback

67

68 A simple configuration may look as follows:

69

70 psql liquid_feedback

71

72 INSERT INTO system_setting (member_ttl) VALUES ('1 year');

73 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);

74 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);

75 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);

76 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);

77 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);

78 INSERT INTO unit (name) VALUES ('Our organization');

79 INSERT INTO area (unit_id, name) VALUES (1, 'Default area');

80 INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);

81

82 If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:

83

84 INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');

85

86 Exit the `psql` interface by typing:

87

88 \q

89

90 And don't forget to quit the `www-data` shell:

91

92 exit

93

94

95 4. Install Moonbridge (only for WebMCP 2.x)

96 -------------------------------------------

97

98 # Download and unpack Moonbridge

99 # from http://www.public-software-group.org/pub/projects/moonbridge/

100 pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua

101 mkdir /opt/moonbridge

102 cp moonbridge /opt/moonbridge/

103 cp moonbridge_http.lua /opt/moonbridge/

104

105

106 5. Install WebMCP

107 -----------------

108

109 Note: Using Debian, it may be necessary to append `-I /usr/include/lua5.2` at

110 the end of the CFLAGS line in `Makefile.options` of the WebMCP source

111 distibution:

112

113 # Download and unpack WebMCP

114 # from http://www.public-software-group.org/pub/projects/webmcp/

115 vi Makefile.options # Debian requires -I /usr/include/lua5.2 at end of CFLAGS line

116 make

117 mkdir /opt/webmcp

118 cp -RL framework/* /opt/webmcp/

119

120

121 6. Install the LiquidFeedback-Frontend

122 --------------------------------------

123

124 Unpack source tree into appropriate directory, e.g. `/opt/liquid_feedback_frontend`:

125

126 # Download LiquidFeedback-Frontend

127 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/

128 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend

129

130 Make `tmp/` directory of LiquidFeedback-Frontend writable for webserver:

131

132 chown www-data /opt/liquid_feedback_frontend/tmp

133

134 Compile binary for fast delivery of member images (only necessary for WebMCP 1.2.x):

135

136 cd /opt/liquid_feedback_frontend/fastpath

137 vi getpic.c # check and modify #define commands as necessary

138 make

139

140

141 7. Configure mail system

142 ------------------------

143

144 It may be necessary to configure your server's mail system, e.g. running

145 `dpkg-reconfigure exim4-config` on a Debian system.

146

147

148 8. Configure the Webserver for LiquidFeedback (only for WebMCP 1.2.x)

149 ---------------------------------------------------------------------

150

151 A sample configuration for `lighttpd` is given below (assuming `mod_alias` has

152 been included elsewhere):

153

154 server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")

155

156 # Enable CGI-Execution of *.lua files through lua binary

157 cgi.assign += ( ".lua" => "/usr/bin/lua5.1" )

158

159 alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/",

160 "/lf/static" => "/opt/liquid_feedback_frontend/static",

161 "/lf" => "/opt/webmcp/cgi-bin" )

162

163 # Configure environment for demo application

164 $HTTP["url"] =~ "^/lf" {

165 setenv.add-environment += (

166 "LANG" => "en_US.UTF-8",

167 "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/",

168 "WEBMCP_CONFIG_NAME" => "myconfig")

169 }

170

171 # URL beautification

172 url.rewrite-once += (

173 # do not rewrite static URLs

174 "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1",

175 "^/lf/static/(.*)$" => "/lf/static/$1",

176

177 # dynamic URLs

178 "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3",

179

180 )

181

182 $HTTP["url"] =~ "^/lf/fastpath/" {

183 cgi.assign = ( "" => "" )

184 setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" )

185 }

186

187 If you're using Debian, you may want to create a file with the name

188 `/etc/lighttpd/conf-available/60-liquidfeedback.conf` and create a softlink in

189 `/etc/lighttpd/conf-enabled/`.

190

191

192 9. Configure the LiquidFeedback-Frontend

193 ----------------------------------------

194

195 cd /opt/liquid_feedback_frontend/config

196 cp example.lua myconfig.lua

197 # edit myconfig.lua according to your needs

198

199 Use the following option in your configuration file to enable fast image

200 loading (only for WebMCP 1.2.x):

201

202 config.fastpath_url_func = function(member_id, image_type)

203 return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)

204 end

205

206

207 10. Setup regular execution of `lf_update` and related commands

208 ---------------------------------------------------------------

209

210 The executables `lf_update`, `lf_update_issue_order`, and

211 `lf_update_suggestion_order` must be executed regularly. This may be achieved

212 by creating a file named `/opt/liquid_feedback_core/lf_updated` with the

213 following contents:

214

215 #!/bin/sh

216

217 PIDFILE="/var/run/lf_updated.pid"

218 PID=$$

219

220 if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then

221 echo "lf_updated is already running."

222 exit 1

223 fi

224

225 echo "${PID}" > "${PIDFILE}"

226

227 while true; do

228 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'

229 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'

230 su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'

231 sleep 5

232 done

233

234 This file must be marked as executable:

235

236 chmod +x /opt/liquid_feedback_core/lf_updated

237

238 And this file should be started automatically at system boot.

239

240

241 11. Setup notification loop in background (only for WebMCP 1.2.x)

242 -----------------------------------------------------------------

243

244 In addition to regular execution of `lf_update` and

245 `lf_update_suggestion_order`, the following commands should be executed in

246 background:

247

248 su - www-data

249 cd /opt/liquid_feedback_frontend/

250 echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig

251

252

253 12. Start the sytem

254 -------------------

255

256 After `lf_update` has been executed at least once, and the webserver has been

257 restarted (using the configuration above), you should be able to access your

258 LiquidFeedback system.

259

260 If you use WebMCP 2.x, the server is started by calling:

261

262 /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig

263