liquid_feedback_frontend

annotate INSTALL.mkd @ 1859:02c34183b6df

find changesets by author, revision, files, or words in the commit message
Fixed wrong filename in INSTALL file
author bsw
date Tue Nov 28 18:54:51 2023 +0100 (5 months ago)
parents 7d000a357704
children
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
bsw@1657 15 * postgresql
bsw@1657 16 * postgresql-server-dev-12
jbe@1308 17 * libbsd-dev
bsw@1657 18 * lua5.3
bsw@1657 19 * liblua5.3-dev
bsw@1657 20 * mercurial
bsw@1657 21 * bmake
bsw@1657 22 * lsb-release
bsw@1045 23 * imagemagick
bsw@1839 24 * sassc
bsw@1045 25
bsw@1045 26 If you're using any other Linux distribution or BSD system, install the
bsw@1045 27 necessary software components accordingly.
bsw@1045 28
bsw@1045 29
bsw@1045 30 2. Ensure that the user account of your webserver has access to the database
bsw@1045 31 ----------------------------------------------------------------------------
bsw@1045 32
bsw@1657 33 The useraccount of Moonbridge server process needs to have access to your
bsw@1657 34 PostgreSQL installation. This is done by executing PostgreSQL's shell command
bsw@1657 35 `createuser` as database superuser (usually `pgsql`, or `postgres` for
bsw@1657 36 Debian installations):
bsw@1045 37
bsw@1657 38 su - postgres -s $SHELL
jbe@1191 39 createuser --no-superuser --createdb --no-createrole www-data
bsw@1045 40 exit
bsw@1045 41
bsw@1045 42
bsw@1045 43 3. Install and configure LiquidFeedback-Core
bsw@1045 44 --------------------------------------------
bsw@1045 45
bsw@1045 46 We recommend to create the database with the same user as your webserver
bsw@1045 47 (usually `www-data`) to avoid having to setup database privileges.
bsw@1045 48
bsw@1657 49 The example below installs the database as `www-data` and stores the three
bsw@1657 50 executables `lf_update`, `lf_update_issue_order` and
bsw@1657 51 `lf_update_suggestion_order` in the directory `/opt/liquid_feedback_core/`:
bsw@1045 52
bsw@1045 53 # 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 psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
bsw@1045 62
bsw@1045 63 A simple configuration may look as follows:
bsw@1045 64
bsw@1045 65 psql liquid_feedback
bsw@1045 66
bsw@1045 67 INSERT INTO system_setting (member_ttl) VALUES ('1 year');
bsw@1045 68 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
bsw@1045 69 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
bsw@1045 70 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
bsw@1045 71 INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
bsw@1045 72
bsw@1657 73 Create an invite code for an admin user:
bsw@1045 74
bsw@1657 75 INSERT INTO member (invite_code, admin) VALUES ('sesam', true);
bsw@1045 76
bsw@1045 77 Exit the `psql` interface by typing:
bsw@1045 78
bsw@1045 79 \q
bsw@1045 80
bsw@1045 81 And don't forget to quit the `www-data` shell:
bsw@1045 82
bsw@1045 83 exit
bsw@1045 84
bsw@1045 85
jbe@1244 86 4. Install Moonbridge
jbe@1244 87 ---------------------
jbe@1156 88
jbe@1156 89 # Download and unpack Moonbridge
jbe@1156 90 # from http://www.public-software-group.org/pub/projects/moonbridge/
jbe@1156 91 pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua
jbe@1156 92 mkdir /opt/moonbridge
jbe@1156 93 cp moonbridge /opt/moonbridge/
jbe@1156 94 cp moonbridge_http.lua /opt/moonbridge/
jbe@1156 95
jbe@1156 96
jbe@1156 97 5. Install WebMCP
bsw@1045 98 -----------------
bsw@1045 99
bsw@1045 100 # Download and unpack WebMCP
bsw@1045 101 # from http://www.public-software-group.org/pub/projects/webmcp/
bsw@1045 102 make
bsw@1045 103 mkdir /opt/webmcp
bsw@1045 104 cp -RL framework/* /opt/webmcp/
bsw@1045 105
bsw@1045 106
jbe@1156 107 6. Install the LiquidFeedback-Frontend
bsw@1045 108 --------------------------------------
bsw@1045 109
bsw@1045 110 Unpack source tree into appropriate directory, e.g. `/opt/liquid_feedback_frontend`:
bsw@1045 111
bsw@1045 112 # Download LiquidFeedback-Frontend
bsw@1045 113 # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
bsw@1045 114 mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
bsw@1045 115
bsw@1045 116 Make `tmp/` directory of LiquidFeedback-Frontend writable for webserver:
bsw@1045 117
bsw@1045 118 chown www-data /opt/liquid_feedback_frontend/tmp
bsw@1045 119
bsw@1045 120
jbe@1156 121 7. Configure mail system
bsw@1045 122 ------------------------
bsw@1045 123
bsw@1657 124 It may be necessary to configure your server's mail system.
bsw@1045 125
bsw@1045 126
jbe@1244 127 8. Configure the LiquidFeedback-Frontend
jbe@1156 128 ----------------------------------------
bsw@1045 129
bsw@1045 130 cd /opt/liquid_feedback_frontend/config
bsw@1045 131 cp example.lua myconfig.lua
bsw@1045 132 # edit myconfig.lua according to your needs
bsw@1045 133
bsw@1045 134
jbe@1244 135 9. Setup regular execution of `lf_update` and related commands
jbe@1244 136 --------------------------------------------------------------
bsw@1045 137
jbe@1051 138 The executables `lf_update`, `lf_update_issue_order`, and
jbe@1051 139 `lf_update_suggestion_order` must be executed regularly. This may be achieved
bsw@1657 140 by creating a file named `/opt/liquid_feedback_core/lf_update.sh` with the
jbe@1051 141 following contents:
bsw@1045 142
bsw@1045 143 #!/bin/sh
bsw@1045 144
bsw@1045 145 while true; do
bsw@1661 146 nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_core"
bsw@1661 147 nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_core"
bsw@1661 148 nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_core"
bsw@1045 149 sleep 5
bsw@1045 150 done
bsw@1045 151
bsw@1045 152 This file must be marked as executable:
bsw@1045 153
bsw@1859 154 chmod +x /opt/liquid_feedback_core/lf_update.sh
bsw@1045 155
bsw@1657 156 And this file should be started automatically at system boot. On systems with
bsw@1657 157 systemd, create a file named `/etc/systemd/system/liquid_feedback_core.service`:
bsw@1657 158
bsw@1657 159 [Unit]
bsw@1657 160 Description=LiquidFeedback Core update
bsw@1657 161
bsw@1657 162 [Service]
bsw@1661 163 User=www-data
bsw@1657 164 ExecStart=/opt/liquid_feedback_core/lf_update.sh
bsw@1657 165
bsw@1657 166 [Install]
bsw@1657 167 WantedBy=multi-user.target
bsw@1657 168
bsw@1657 169 Enable and start the service:
bsw@1673 170
bsw@1657 171 systemctl start liquid_feedback_core
bsw@1657 172 systemctl enable liquid_feedback_core
bsw@1045 173
bsw@1045 174
bsw@1657 175 10. Start the frontend
bsw@1657 176 ----------------------
bsw@1045 177
jbe@1244 178 After `lf_update` has been executed at least once, you should be able to use
jbe@1244 179 your LiquidFeedback system.
bsw@1045 180
bsw@1674 181 Create a file named `/opt/liquid_feedback_frontend/run.sh`:
bsw@1657 182
bsw@1657 183 #/bin/bash
bsw@1657 184
bsw@1661 185 /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig 2>&1 | logger -t "lf_frontend"
bsw@1657 186
bsw@1657 187 Make it executable:
bsw@1657 188
bsw@1657 189 chmod +x /opt/liquid_feedback_frontend/run.sh
bsw@1657 190
bsw@1657 191 On systemd based systems, create a file named
bsw@1657 192 `/etc/systemd/system/liquid_feedback_frontend.service`:
bsw@1045 193
bsw@1657 194 [Unit]
bsw@1657 195 Description=LiquidFeedback Frontend
bsw@1657 196
bsw@1657 197 [Service]
bsw@1661 198 User=www-data
bsw@1657 199 ExecStart=/opt/liquid_feedback_frontend/run.sh
bsw@1657 200
bsw@1657 201 [Install]
bsw@1657 202 WantedBy=multi-user.target
bsw@1657 203
bsw@1657 204 Enable and start the service:
bsw@1673 205
bsw@1657 206 systemctl start liquid_feedback_frontend
bsw@1657 207 systemctl enable liquid_feedback_frontend
bsw@1657 208
jbe@1156 209
jbe@1162 210 In the latter case, the Moonbridge server will open a TCP port according to
jbe@1162 211 your configuration. Directly accessing this TCP port through your webbrowser
jbe@1162 212 is helpful for development purposes. For real-life deployment, however, it is
jbe@1162 213 recommended to further proxy the application (e.g. using nginx). The proxy can
jbe@1190 214 also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge
jbe@1190 215 itself).
jbe@1190 216
jbe@1190 217

Impressum / About Us