bsw@1045: LiquidFeedback Installation Instructions bsw@1045: ======================================== bsw@1045: bsw@1045: This document gives a short outline about the necessary steps to setup a bsw@1045: LiquidFeedback system. bsw@1045: bsw@1045: bsw@1045: 1. Install necessary dependencies bsw@1045: --------------------------------- bsw@1045: bsw@1045: If you're using a Debian system, make sure that the following packages are bsw@1045: installed: bsw@1045: jbe@1156: * build-essential bsw@1657: * postgresql bsw@1657: * postgresql-server-dev-12 jbe@1308: * libbsd-dev bsw@1657: * lua5.3 bsw@1657: * liblua5.3-dev bsw@1657: * mercurial bsw@1657: * bmake bsw@1657: * lsb-release bsw@1045: * imagemagick bsw@1045: bsw@1045: If you're using any other Linux distribution or BSD system, install the bsw@1045: necessary software components accordingly. bsw@1045: bsw@1045: bsw@1045: 2. Ensure that the user account of your webserver has access to the database bsw@1045: ---------------------------------------------------------------------------- bsw@1045: bsw@1657: The useraccount of Moonbridge server process needs to have access to your bsw@1657: PostgreSQL installation. This is done by executing PostgreSQL's shell command bsw@1657: `createuser` as database superuser (usually `pgsql`, or `postgres` for bsw@1657: Debian installations): bsw@1045: bsw@1657: su - postgres -s $SHELL jbe@1191: createuser --no-superuser --createdb --no-createrole www-data bsw@1045: exit bsw@1045: bsw@1045: bsw@1045: 3. Install and configure LiquidFeedback-Core bsw@1045: -------------------------------------------- bsw@1045: bsw@1045: We recommend to create the database with the same user as your webserver bsw@1045: (usually `www-data`) to avoid having to setup database privileges. bsw@1045: bsw@1657: The example below installs the database as `www-data` and stores the three bsw@1657: executables `lf_update`, `lf_update_issue_order` and bsw@1657: `lf_update_suggestion_order` in the directory `/opt/liquid_feedback_core/`: bsw@1045: bsw@1045: # Download and unpack LiquidFeedback-Core bsw@1045: # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/ bsw@1045: make bsw@1045: mkdir /opt/liquid_feedback_core jbe@1196: cp core.sql lf_update lf_update_issue_order lf_update_suggestion_order /opt/liquid_feedback_core jbe@1191: su www-data -s $SHELL bsw@1045: cd /opt/liquid_feedback_core bsw@1045: createdb liquid_feedback bsw@1045: psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback bsw@1045: bsw@1045: A simple configuration may look as follows: bsw@1045: bsw@1045: psql liquid_feedback bsw@1045: bsw@1045: INSERT INTO system_setting (member_ttl) VALUES ('1 year'); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60); bsw@1045: INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120); bsw@1045: bsw@1657: Create an invite code for an admin user: bsw@1045: bsw@1657: INSERT INTO member (invite_code, admin) VALUES ('sesam', true); bsw@1045: bsw@1045: Exit the `psql` interface by typing: bsw@1045: bsw@1045: \q bsw@1045: bsw@1045: And don't forget to quit the `www-data` shell: bsw@1045: bsw@1045: exit bsw@1045: bsw@1045: jbe@1244: 4. Install Moonbridge jbe@1244: --------------------- jbe@1156: jbe@1156: # Download and unpack Moonbridge jbe@1156: # from http://www.public-software-group.org/pub/projects/moonbridge/ jbe@1156: pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua jbe@1156: mkdir /opt/moonbridge jbe@1156: cp moonbridge /opt/moonbridge/ jbe@1156: cp moonbridge_http.lua /opt/moonbridge/ jbe@1156: jbe@1156: jbe@1156: 5. Install WebMCP bsw@1045: ----------------- bsw@1045: bsw@1045: # Download and unpack WebMCP bsw@1045: # from http://www.public-software-group.org/pub/projects/webmcp/ bsw@1045: make bsw@1045: mkdir /opt/webmcp bsw@1045: cp -RL framework/* /opt/webmcp/ bsw@1045: bsw@1045: jbe@1156: 6. Install the LiquidFeedback-Frontend bsw@1045: -------------------------------------- bsw@1045: bsw@1045: Unpack source tree into appropriate directory, e.g. `/opt/liquid_feedback_frontend`: bsw@1045: bsw@1045: # Download LiquidFeedback-Frontend bsw@1045: # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/ bsw@1045: mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend bsw@1045: bsw@1045: Make `tmp/` directory of LiquidFeedback-Frontend writable for webserver: bsw@1045: bsw@1045: chown www-data /opt/liquid_feedback_frontend/tmp bsw@1045: bsw@1045: jbe@1156: 7. Configure mail system bsw@1045: ------------------------ bsw@1045: bsw@1657: It may be necessary to configure your server's mail system. bsw@1045: bsw@1045: jbe@1244: 8. Configure the LiquidFeedback-Frontend jbe@1156: ---------------------------------------- bsw@1045: bsw@1045: cd /opt/liquid_feedback_frontend/config bsw@1045: cp example.lua myconfig.lua bsw@1045: # edit myconfig.lua according to your needs bsw@1045: bsw@1045: jbe@1244: 9. Setup regular execution of `lf_update` and related commands jbe@1244: -------------------------------------------------------------- bsw@1045: jbe@1051: The executables `lf_update`, `lf_update_issue_order`, and jbe@1051: `lf_update_suggestion_order` must be executed regularly. This may be achieved bsw@1657: by creating a file named `/opt/liquid_feedback_core/lf_update.sh` with the jbe@1051: following contents: bsw@1045: bsw@1045: #!/bin/sh bsw@1045: bsw@1045: while true; do bsw@1661: nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_core" bsw@1661: nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_core" bsw@1661: nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_core" bsw@1045: sleep 5 bsw@1045: done bsw@1045: bsw@1045: This file must be marked as executable: bsw@1045: bsw@1045: chmod +x /opt/liquid_feedback_core/lf_updated bsw@1045: bsw@1657: And this file should be started automatically at system boot. On systems with bsw@1657: systemd, create a file named `/etc/systemd/system/liquid_feedback_core.service`: bsw@1657: bsw@1657: [Unit] bsw@1657: Description=LiquidFeedback Core update bsw@1657: bsw@1657: [Service] bsw@1661: User=www-data bsw@1657: ExecStart=/opt/liquid_feedback_core/lf_update.sh bsw@1657: bsw@1657: [Install] bsw@1657: WantedBy=multi-user.target bsw@1657: bsw@1657: Enable and start the service: bsw@1657: systemctl start liquid_feedback_core bsw@1657: systemctl enable liquid_feedback_core bsw@1045: bsw@1045: bsw@1657: 10. Start the frontend bsw@1657: ---------------------- bsw@1045: jbe@1244: After `lf_update` has been executed at least once, you should be able to use jbe@1244: your LiquidFeedback system. bsw@1045: bsw@1657: Create a file named "/opt/liquid_feedback_frontend/run.sh": bsw@1657: bsw@1657: #/bin/bash bsw@1657: bsw@1661: /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig 2>&1 | logger -t "lf_frontend" bsw@1657: bsw@1657: Make it executable: bsw@1657: bsw@1657: chmod +x /opt/liquid_feedback_frontend/run.sh bsw@1657: bsw@1657: On systemd based systems, create a file named bsw@1657: `/etc/systemd/system/liquid_feedback_frontend.service`: bsw@1045: bsw@1657: [Unit] bsw@1657: Description=LiquidFeedback Frontend bsw@1657: bsw@1657: [Service] bsw@1661: User=www-data bsw@1657: ExecStart=/opt/liquid_feedback_frontend/run.sh bsw@1657: bsw@1657: [Install] bsw@1657: WantedBy=multi-user.target bsw@1657: bsw@1657: Enable and start the service: bsw@1657: systemctl start liquid_feedback_frontend bsw@1657: systemctl enable liquid_feedback_frontend bsw@1657: jbe@1156: jbe@1162: In the latter case, the Moonbridge server will open a TCP port according to jbe@1162: your configuration. Directly accessing this TCP port through your webbrowser jbe@1162: is helpful for development purposes. For real-life deployment, however, it is jbe@1162: recommended to further proxy the application (e.g. using nginx). The proxy can jbe@1190: also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge jbe@1190: itself). jbe@1190: jbe@1190: