LiquidFeedback Installation Instructions
========================================

This document gives a short outline about the necessary steps to setup a
LiquidFeedback system.


1. Install necessary dependencies
---------------------------------

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

  * build-essential
  * postgresql
  * postgresql-server-dev-12
  * libbsd-dev
  * lua5.3
  * liblua5.3-dev
  * mercurial
  * bmake
  * lsb-release
  * imagemagick

If you're using any other Linux distribution or BSD system, install the
necessary software components accordingly.


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

The useraccount of Moonbridge server process needs to have access to your
PostgreSQL installation. This is done by executing PostgreSQL's shell command
`createuser` as database superuser (usually `pgsql`, or `postgres` for
Debian installations):

    su - postgres -s $SHELL
    createuser --no-superuser --createdb --no-createrole www-data
    exit


3. Install and configure LiquidFeedback-Core
--------------------------------------------

We recommend to create the database with the same user as your webserver
(usually `www-data`) to avoid having to setup database privileges.

The example below installs the database as `www-data` and stores the three
executables `lf_update`, `lf_update_issue_order` and
`lf_update_suggestion_order` in the directory `/opt/liquid_feedback_core/`:

    # Download and unpack LiquidFeedback-Core
    # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
    make
    mkdir /opt/liquid_feedback_core
    cp core.sql lf_update lf_update_issue_order lf_update_suggestion_order /opt/liquid_feedback_core
    su www-data -s $SHELL
    cd /opt/liquid_feedback_core
    createdb liquid_feedback
    psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback

A simple configuration may look as follows:

    psql liquid_feedback

    INSERT INTO system_setting (member_ttl) VALUES ('1 year');
    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);

Create an invite code for an admin user:

    INSERT INTO member (invite_code, admin) VALUES ('sesam', true);

Exit the `psql` interface by typing:

    \q

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

    exit


4. Install Moonbridge
---------------------

    # Download and unpack Moonbridge
    # from http://www.public-software-group.org/pub/projects/moonbridge/
    pmake MOONBR_LUA_PATH=/opt/moonbridge/?.lua
    mkdir /opt/moonbridge
    cp moonbridge /opt/moonbridge/
    cp moonbridge_http.lua /opt/moonbridge/


5. Install WebMCP
-----------------

    # Download and unpack WebMCP
    # from http://www.public-software-group.org/pub/projects/webmcp/
    make
    mkdir /opt/webmcp
    cp -RL framework/* /opt/webmcp/


6. Install the LiquidFeedback-Frontend
--------------------------------------

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

    # Download LiquidFeedback-Frontend
    # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
    mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend

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

    chown www-data /opt/liquid_feedback_frontend/tmp


7. Configure mail system
------------------------

It may be necessary to configure your server's mail system.


8. Configure the LiquidFeedback-Frontend
----------------------------------------

    cd /opt/liquid_feedback_frontend/config
    cp example.lua myconfig.lua
    # edit myconfig.lua according to your needs


9. Setup regular execution of `lf_update` and related commands 
--------------------------------------------------------------

The executables `lf_update`, `lf_update_issue_order`, and
`lf_update_suggestion_order` must be executed regularly. This may be achieved
by creating a file named `/opt/liquid_feedback_core/lf_update.sh` with the
following contents:

    #!/bin/sh

    while true; do
      nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_core"
      nice /opt/liquid_feedback_core/lf_update_issue_order dbname=liquid_feedback 2>&1 | logger -t "lf_core"
      nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_core"
      sleep 5
    done

This file must be marked as executable:

    chmod +x /opt/liquid_feedback_core/lf_updated

And this file should be started automatically at system boot. On systems with
systemd, create a file named `/etc/systemd/system/liquid_feedback_core.service`:

    [Unit]
    Description=LiquidFeedback Core update

    [Service]
    User=www-data
    ExecStart=/opt/liquid_feedback_core/lf_update.sh

    [Install]
    WantedBy=multi-user.target

Enable and start the service:

    systemctl start liquid_feedback_core
    systemctl enable liquid_feedback_core


10. Start the frontend
----------------------

After `lf_update` has been executed at least once, you should be able to use
your LiquidFeedback system.

Create a file named `/opt/liquid_feedback_frontend/run.sh`:

    #/bin/bash
    
    /opt/moonbridge/moonbridge /opt/webmcp/bin/mcp.lua /opt/webmcp/ /opt/liquid_feedback_frontend/ main myconfig  2>&1 | logger -t "lf_frontend"

Make it executable:

    chmod +x /opt/liquid_feedback_frontend/run.sh

On systemd based systems, create a file named
`/etc/systemd/system/liquid_feedback_frontend.service`:

    [Unit]
    Description=LiquidFeedback Frontend

    [Service]
    User=www-data
    ExecStart=/opt/liquid_feedback_frontend/run.sh

    [Install]
    WantedBy=multi-user.target

Enable and start the service:

    systemctl start liquid_feedback_frontend
    systemctl enable liquid_feedback_frontend


In the latter case, the Moonbridge server will open a TCP port according to
your configuration. Directly accessing this TCP port through your webbrowser
is helpful for development purposes. For real-life deployment, however, it is
recommended to further proxy the application (e.g. using nginx). The proxy can
also add HTTPS and/or HTTP/2 support (which is not supported by Moonbridge
itself).


