1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/INSTALL.mkd	Thu Jul 10 01:19:48 2014 +0200
     1.3 @@ -0,0 +1,289 @@
     1.4 +LiquidFeedback Installation Instructions
     1.5 +========================================
     1.6 +
     1.7 +This document gives a short outline about the necessary steps to setup a
     1.8 +LiquidFeedback system.
     1.9 +
    1.10 +
    1.11 +1. Install necessary dependencies
    1.12 +---------------------------------
    1.13 +
    1.14 +If you're using a Debian system, make sure that the following packages are
    1.15 +installed:
    1.16 +
    1.17 +  * lua5.1
    1.18 +  * postgresql
    1.19 +  * build-essential
    1.20 +  * libpq-dev
    1.21 +  * liblua5.1-0-dev
    1.22 +  * lighttpd
    1.23 +  * ghc
    1.24 +  * libghc6-parsec3-dev
    1.25 +  * imagemagick
    1.26 +  * exim4
    1.27 +
    1.28 +If you're using any other Linux distribution or BSD system, install the
    1.29 +necessary software components accordingly.
    1.30 +
    1.31 +
    1.32 +2. Ensure that the user account of your webserver has access to the database
    1.33 +----------------------------------------------------------------------------
    1.34 +
    1.35 +Whichever useraccount is used by the webserver (usually `www-data`) needs to
    1.36 +have access to your PostgreSQL installation. This is done by executing
    1.37 +PostgreSQL's shell command `createuser` as database superuser (usually `pgsql`,
    1.38 +or `postgres` for Debian installations):
    1.39 +
    1.40 +    su - postgres
    1.41 +    createuser
    1.42 +
    1.43 +    Enter name of role to add: www-data
    1.44 +    Shall the new role be a superuser? (y/n) n
    1.45 +    Shall the new role be allowed to create databases? (y/n) y
    1.46 +    Shall the new role be allowed to create more new roles? (y/n) n
    1.47 +
    1.48 +    exit
    1.49 +
    1.50 +
    1.51 +3. Install and configure LiquidFeedback-Core
    1.52 +--------------------------------------------
    1.53 +
    1.54 +We recommend to create the database with the same user as your webserver
    1.55 +(usually `www-data`) to avoid having to setup database privileges.
    1.56 +
    1.57 +The example below installs the database as `www-data` and stores the two
    1.58 +executables `lf_update` and `lf_update_issue_order` in the directory
    1.59 +`/opt/liquid_feedback_core/`:
    1.60 +
    1.61 +    # Download and unpack LiquidFeedback-Core
    1.62 +    # from http://www.public-software-group.org/pub/projects/liquid_feedback/backend/
    1.63 +    make
    1.64 +    mkdir /opt/liquid_feedback_core
    1.65 +    cp core.sql lf_update lf_update_issue_order /opt/liquid_feedback_core
    1.66 +    su - www-data
    1.67 +    cd /opt/liquid_feedback_core
    1.68 +    createdb liquid_feedback
    1.69 +    createlang plpgsql liquid_feedback  # command may be omitted, depending on PostgreSQL version
    1.70 +    psql -v ON_ERROR_STOP=1 -f core.sql liquid_feedback
    1.71 +
    1.72 +A simple configuration may look as follows:
    1.73 +
    1.74 +    psql liquid_feedback
    1.75 +
    1.76 +    INSERT INTO system_setting (member_ttl) VALUES ('1 year');
    1.77 +    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 hour', 20, 6);
    1.78 +    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (false, '1 day', 80, 12);
    1.79 +    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 hour', 200, 60);
    1.80 +    INSERT INTO contingent (polling, time_frame, text_entry_limit, initiative_limit) VALUES (true, '1 day', 800, 120);
    1.81 +    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);
    1.82 +    INSERT INTO unit (name) VALUES ('Our organization');
    1.83 +    INSERT INTO area (unit_id, name) VALUES (1, 'Default area');
    1.84 +    INSERT INTO allowed_policy (area_id, policy_id, default_policy) VALUES (1, 1, TRUE);
    1.85 +
    1.86 +If you want to create an admin user with an empty password (CAUTION!), then execute the following SQL statement:
    1.87 +
    1.88 +    INSERT INTO member (login, name, admin, password) VALUES ('admin', 'Administrator', TRUE, '$1$/EMPTY/$NEWt7XJg2efKwPm4vectc1');
    1.89 +
    1.90 +Exit the `psql` interface by typing:
    1.91 +
    1.92 +    \q
    1.93 +
    1.94 +And don't forget to quit the `www-data` shell:
    1.95 +
    1.96 +    exit
    1.97 +
    1.98 +
    1.99 +4. Install WebMCP
   1.100 +-----------------
   1.101 +
   1.102 +Note: Using Debian, it may be necessary to append `-I /usr/include/lua5.1` at
   1.103 +the end of the CFLAGS line in `Makefile.options` of the WebMCP source
   1.104 +distibution:
   1.105 +
   1.106 +    # Download and unpack WebMCP
   1.107 +    # from http://www.public-software-group.org/pub/projects/webmcp/
   1.108 +    vi Makefile.options  # Debian requires  -I /usr/include/lua5.1  at end of CFLAGS line
   1.109 +    make
   1.110 +    mkdir /opt/webmcp
   1.111 +    cp -RL framework/* /opt/webmcp/
   1.112 +
   1.113 +
   1.114 +5. Install RocketWiki LqFb-Edition
   1.115 +----------------------------------
   1.116 +
   1.117 +    # Download and unpack "RocketWiki LqFb-Edition"
   1.118 +    # from http://www.public-software-group.org/pub/projects/rocketwiki/liquid_feedback_edition/
   1.119 +    make
   1.120 +    mkdir /opt/rocketwiki-lqfb
   1.121 +    cp rocketwiki-lqfb rocketwiki-lqfb-compat /opt/rocketwiki-lqfb/
   1.122 +
   1.123 +If you experience problems with multi-byte encoding (UTF-8) later, then apply
   1.124 +the following patch to both `rocketwiki-lqfb.hs` and
   1.125 +`rocketwiki-lqfb-compat.hs` prior compilation:
   1.126 +
   1.127 +    --- rocketwiki-lqfb.hs
   1.128 +    +++ rocketwiki-lqfb.hs
   1.129 +    @@ -1,4 +1,6 @@
   1.130 + 
   1.131 +    +import System.IO (hSetEncoding, stdin, stdout, utf8)
   1.132 +    +
   1.133 +     import Text.ParserCombinators.Parsec
   1.134 +     import Control.Applicative ((<$>), (<*>))
   1.135 +     import Data.List (intercalate)
   1.136 +    @@ -405,7 +407,10 @@
   1.137 +           return htmlEntity
   1.138 +     
   1.139 +     
   1.140 +    -main = interact wikiParse
   1.141 +    +main = do
   1.142 +    +  hSetEncoding stdin utf8
   1.143 +    +  hSetEncoding stdout utf8
   1.144 +    +  interact wikiParse
   1.145 + 
   1.146 +     wikiParse str
   1.147 +       | success parseResult = html
   1.148 +
   1.149 +
   1.150 +6. Install the LiquidFeedback-Frontend
   1.151 +--------------------------------------
   1.152 +
   1.153 +Unpack source tree into appropriate directory, e.g. `/opt/liquid_feedback_frontend`:
   1.154 +
   1.155 +    # Download LiquidFeedback-Frontend
   1.156 +    # from http://www.public-software-group.org/pub/projects/liquid_feedback/frontend/
   1.157 +    mv liquid_feedback_frontend-vX.X.X /opt/liquid_feedback_frontend
   1.158 +
   1.159 +Create HTML code for help texts:
   1.160 +
   1.161 +    cd /opt/liquid_feedback_frontend/locale
   1.162 +    PATH=/opt/rocketwiki-lqfb:$PATH make
   1.163 +
   1.164 +Make `tmp/` directory of LiquidFeedback-Frontend writable for webserver:
   1.165 +
   1.166 +    chown www-data /opt/liquid_feedback_frontend/tmp
   1.167 +
   1.168 +Compile binary for fast delivery of member images:
   1.169 +
   1.170 +    cd /opt/liquid_feedback_frontend/fastpath
   1.171 +    vi getpic.c  # check and modify #define commands as necessary
   1.172 +    make
   1.173 +
   1.174 +
   1.175 +7. Configure mail system
   1.176 +------------------------
   1.177 +
   1.178 +It may be necessary to configure your server's mail system, e.g. running
   1.179 +`dpkg-reconfigure exim4-config` on a Debian system.
   1.180 +
   1.181 +
   1.182 +8. Configure the Webserver for LiquidFeedback:
   1.183 +----------------------------------------------
   1.184 +
   1.185 +A sample configuration for `lighttpd` is given below (assuming `mod_alias` has
   1.186 +been included elsewhere):
   1.187 +
   1.188 +    server.modules += ("mod_cgi", "mod_rewrite", "mod_redirect", "mod_setenv")
   1.189 +
   1.190 +    # Enable CGI-Execution of *.lua files through lua binary
   1.191 +    cgi.assign += ( ".lua" => "/usr/bin/lua5.1" )
   1.192 +
   1.193 +    alias.url += ( "/lf/fastpath/" => "/opt/liquid_feedback_frontend/fastpath/",
   1.194 +                   "/lf/static"    => "/opt/liquid_feedback_frontend/static",
   1.195 +                   "/lf"           => "/opt/webmcp/cgi-bin" )
   1.196 +
   1.197 +    # Configure environment for demo application
   1.198 +    $HTTP["url"] =~ "^/lf" {
   1.199 +      setenv.add-environment += (
   1.200 +        "LANG" => "en_US.UTF-8",
   1.201 +        "WEBMCP_APP_BASEPATH" => "/opt/liquid_feedback_frontend/",
   1.202 +        "WEBMCP_CONFIG_NAME"  => "myconfig")
   1.203 +    }
   1.204 +
   1.205 +    # URL beautification
   1.206 +    url.rewrite-once += (
   1.207 +      # do not rewrite static URLs
   1.208 +          "^/lf/fastpath/(.*)$" => "/lf/fastpath/$1",
   1.209 +          "^/lf/static/(.*)$"   => "/lf/static/$1",
   1.210 +
   1.211 +      # dynamic URLs
   1.212 +          "^/lf/([^\?]*)(\?(.*))?$" => "/lf/webmcp-wrapper.lua?_webmcp_path=$1&$3",
   1.213 +
   1.214 +    )
   1.215 +
   1.216 +    $HTTP["url"] =~ "^/lf/fastpath/" {
   1.217 +      cgi.assign = ( "" => "" )
   1.218 +      setenv.add-response-header = ( "Cache-Control" => "private; max-age=86400" )
   1.219 +    }
   1.220 +
   1.221 +If you're using Debian, you may want to create a file with the name
   1.222 +`/etc/lighttpd/conf-available/60-liquidfeedback.conf` and create a softlink in
   1.223 +`/etc/lighttpd/conf-enabled/`.
   1.224 +
   1.225 +
   1.226 +9. Configure the LiquidFeedback-Frontend:
   1.227 +-----------------------------------------
   1.228 +
   1.229 +    cd /opt/liquid_feedback_frontend/config
   1.230 +    cp example.lua myconfig.lua
   1.231 +    # edit myconfig.lua according to your needs
   1.232 +
   1.233 +Use the following option in your configuration file to enable fast image
   1.234 +loading:
   1.235 +
   1.236 +    config.fastpath_url_func = function(member_id, image_type)
   1.237 +      return request.get_absolute_baseurl() .. "fastpath/getpic?" .. tostring(member_id) .. "+" .. tostring(image_type)
   1.238 +    end
   1.239 +
   1.240 +
   1.241 +10. Setup regular execution of `lf_update` and `lf_update_suggestion_order`
   1.242 +---------------------------------------------------------------------------
   1.243 +
   1.244 +The executables `lf_update` and `lf_update_suggestion_order` must be executed
   1.245 +regularly. This may be achieved by creating a file named
   1.246 +`/opt/liquid_feedback_core/lf_updated` with the following contents:
   1.247 +
   1.248 +    #!/bin/sh
   1.249 +
   1.250 +    PIDFILE="/var/run/lf_updated.pid"
   1.251 +    PID=$$
   1.252 +
   1.253 +    if [ -f "${PIDFILE}" ] && kill -CONT $( cat "${PIDFILE}" ); then
   1.254 +      echo "lf_updated is already running."
   1.255 +      exit 1
   1.256 +    fi
   1.257 +
   1.258 +    echo "${PID}" > "${PIDFILE}"
   1.259 +
   1.260 +    while true; do
   1.261 +      su - www-data -c 'nice /opt/liquid_feedback_core/lf_update dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
   1.262 +      su - www-data -c 'nice /opt/liquid_feedback_core/lf_update_suggestion_order dbname=liquid_feedback 2>&1 | logger -t "lf_updated"'
   1.263 +      sleep 5
   1.264 +    done
   1.265 +
   1.266 +This file must be marked as executable:
   1.267 +
   1.268 +    chmod +x /opt/liquid_feedback_core/lf_updated
   1.269 +
   1.270 +And this file should be started automatically at system boot.
   1.271 +
   1.272 +
   1.273 +11. Setup notification loop in background
   1.274 +-----------------------------------------
   1.275 +
   1.276 +In addition to regular execution of `lf_update` and
   1.277 +`lf_update_suggestion_order`, the following commands should be executed in
   1.278 +background:
   1.279 +
   1.280 +    su - www-data
   1.281 +    cd /opt/liquid_feedback_frontend/
   1.282 +    echo "Event:send_notifications_loop()" | ../webmcp/bin/webmcp_shell myconfig
   1.283 +
   1.284 +
   1.285 +12. Start the sytem
   1.286 +-------------------
   1.287 +
   1.288 +After `lf_update` has been executed at least once, and the webserver has been
   1.289 +restarted (using the configuration above), you should be able to access your
   1.290 +LiquidFeedback system.
   1.291 +
   1.292 +