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 * lua5.1

15 * postgresql

16 * build-essential

17 * libpq-dev

18 * liblua5.1-0-dev

19 * lighttpd

20 * ghc

21 * libghc6-parsec3-dev

22 * imagemagick

23 * exim4

24 * markdown2 (install with Python's pip)

25

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

27 necessary software components accordingly.

28

29

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

31 ----------------------------------------------------------------------------

32

33 Whichever useraccount is used by the webserver (usually `www-data`) needs to

34 have access to your PostgreSQL installation. This is done by executing

35 PostgreSQL's shell command `createuser` as database superuser (usually `pgsql`,

36 or `postgres` for Debian installations):

37

38 su - postgres

39 createuser

40

41 Enter name of role to add: www-data

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

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

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

45

46 exit

47

48

49 3. Install and configure LiquidFeedback-Core

50 --------------------------------------------

51

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

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

54

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

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

57 `/opt/liquid_feedback_core/`:

58

59 # Download and unpack LiquidFeedback-Core

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

61 make

62 mkdir /opt/liquid_feedback_core

63 cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core

64 su - www-data

65 cd /opt/liquid_feedback_core

66 createdb liquid_feedback

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

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

69

70 A simple configuration may look as follows:

71

72 psql liquid_feedback

73

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

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

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

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

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

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

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

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

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

83

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

85

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

87

88 Exit the `psql` interface by typing:

89

90 \q

91

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

93

94 exit

95

96

97 4. Install WebMCP

98 -----------------

99

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

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

102 distibution:

103

104 # Download and unpack WebMCP

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

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

107 make

108 mkdir /opt/webmcp

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

110

111

112 5. Install the LiquidFeedback-Frontend

113 --------------------------------------

114

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

116

117 # Download LiquidFeedback-Frontend

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

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

120

121 Create HTML code for help texts:

122

123 cd /opt/liquid_feedback_frontend/locale

124 PATH=/opt/rocketwiki-lqfb:$PATH make

125

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

127

128 chown www-data /opt/liquid_feedback_frontend/tmp

129

130 Compile binary for fast delivery of member images:

131

132 cd /opt/liquid_feedback_frontend/fastpath

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

134 make

135

136

137 6. Configure mail system

138 ------------------------

139

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

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

142

143

144 7. Configure the Webserver for LiquidFeedback:

145 ----------------------------------------------

146

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

148 been included elsewhere):

149

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

151

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

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

154

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

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

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

158

159 # Configure environment for demo application

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

161 setenv.add-environment += (

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

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

164 "WEBMCP_CONFIG_NAME" => "myconfig")

165 }

166

167 # URL beautification

168 url.rewrite-once += (

169 # do not rewrite static URLs

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

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

172

173 # dynamic URLs

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

175

176 )

177

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

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

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

181 }

182

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

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

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

186

187

188 8. Configure the LiquidFeedback-Frontend:

189 -----------------------------------------

190

191 cd /opt/liquid_feedback_frontend/config

192 cp example.lua myconfig.lua

193 # edit myconfig.lua according to your needs

194

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

196 loading:

197

198 config.fastpath_url_func = function(member_id, image_type)

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

200 end

201

202

203 9. Setup regular execution of `lf_update` and `lf_update_suggestion_order`

204 ---------------------------------------------------------------------------

205

206 The executables `lf_update` and `lf_update_suggestion_order` must be executed

207 regularly. This may be achieved by creating a file named

208 `/opt/liquid_feedback_core/lf_updated` with the following contents:

209

210 #!/bin/sh

211

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

213 PID=$$

214

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

216 echo "lf_updated is already running."

217 exit 1

218 fi

219

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

221

222 while true; do

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

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

225 sleep 5

226 done

227

228 This file must be marked as executable:

229

230 chmod +x /opt/liquid_feedback_core/lf_updated

231

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

233

234

235 10. Setup notification loop in background

236 -----------------------------------------

237

238 In addition to regular execution of `lf_update` and

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

240 background:

241

242 su - www-data

243 cd /opt/liquid_feedback_frontend/

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

245

246

247 11. Start the sytem

248 -------------------

249

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

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

252 LiquidFeedback system.

253

254