Visit liqd.de

Adhocracy/Installation/en

From LiquidDemocracy

Installing Adhocracy is, unfortunately, a complicated process. The administrator should have at least some experience in dealing with Python packages, Unix shell commands and building packages from SVN checkouts.

Contents

[edit] Dependencies

The following packages are required to run Adhocracy on your own machine:

  • Python, version 2.5 or later. Python is included in most modern operating system distributions. Users of older Debian releases need to make sure they're using Python 2.5 instead of 2.4.
  • RabbitMQ is used as a messaging queue for event notifications and search index updates.
    • While Adhocracy does run without a queue, message processing is a time-intensive process and can lead to slow response times when creating comments, issues and proposals.
    • Theoretically, any message queue compatible with the AMQP protocol should be fine. This includes ActiveMQ and RedHat MRG. While we have not tested we'd like to hear about your experiences.
    • Debian users: The RabbitMQ folks maintain a very good apt source.
    • Mac OS X users: MacPorts has rabbitmq-server.
    • If you install the queue on a machine connected to the internet, make sure that RabbitMQ only accepts connections from within your network, e.g. by setting up an appropriate firewall configuration.
  • Memcached is used for results caching. Using a memcache instance with as little as 32 megabytes of memory will accelerate the application by several orders of magintude.
    • Debian users: you're in luck, recent Debian distributions include a memcached package.
    • Mac OS X users: MacPorts has memcached.
    • Also make sure never to use the same memcached instance for two unrelated installations of Adhocracy. The caching mechanism will not discriminate between the applications and thus return erroneous results.
  • Python Imaging: While it is among the package dependencies of Adhocracy, some users have reported that the automated installation of the library fails on their machine.
    • Debian users: lucky buggers, python-imaging is available via APT.
    • Everyone else: grab the source and build & install.
  • Database: You will need a Python DB API-compatible package to connect to a database.
    • SQLite drivers are included with Python but should only be used for testing setups.
    • PostgreSQL is best accessed through psycopg2 (Debian: python-psycopg2, Mac OS X: you're in a world of pain now).
    • MySQL uses the MySQLdb module. (Debian: python-mysqldb, everyone else: get the package and build it).
    • Other databases may work but are not recommended (the OpenID component will not work properly on other DBMS).

[edit] Preflight Entertainment

The guide assumes that you're installing Adhocracy at /opt/adhocracy and that you've created a dedicated user called adhocracy. These assumptions are, of course, not neccessary and would probably be impractical when in a testing or development environment.

[edit] virtualenv

Adhocracy installs about five metric tons of Python packages. In order to keep your Python install clean, lean and mean, you will want to use a virtualenv. To get going, try this: 

 # easy_install virtualenv
 [gibberish]
 # su adhocracy 
 $ python virtualenv.py /opt/adhocracy/env
 [more gibberish]
 $ source /opt/adhocracy/env/bin/activate

Whenever you enter the virtualenv, distutils will only install packages to the virtualenv's library instead of your real site-packages directory.

[edit] Domain Names

Adhocracy uses a scheme in which a single installation can serve as a host for many user groups. These user groups would then access a selection of distinct instances which share little but the user registration data.

In order to identify the active instance, Adhocracy uses domain names. Therefore, if Adhocracy is installed at a domain name like example.com, instances would be accessed via instance.example.com.

This means that in a production environment, you will want a wild card DNS record to point to the Adhocracy server. For testing purposes, we usually set up a fake domain in our local /etc/hosts file: 

 127.0.0.1 adhocracy.lan test.adhocracy.lan another.adhocracy.lan

For simpler setups, a single-instance Adhocracy mode is planned but not yet implemented.

[edit] Getting Adhocracy

Adhocracy is currently not released in a packaged form. If you want to deveop the application, try a checkout from the SVN Repository. Also read the development docs.

If you just want to install Adhocracy for deployment, directly check out the Package via easy_install. This will not leave you with a repo checkout to work on, but it is cleaner and simpler than raw SVN. 

 $ easy_install http://svn.adhocracy.de/trunk

This will install any required Python libraries, including Pylons, Paste, SQLAlchemy, repoze.who, repoze.what, whoosh and a few others.

[edit] Configuration

First off, create a new database user and an empty database. Make sure to set UTF-8/Unicode as the default encoding wherever necessary.

Adhocracy is configured using an .ini file. The default configuration is stored in a template called development.ini. To begin your configuration, create a copy of the file that you will work on: 

 $ cd /opt/adhocracy
 $ cp development.ini example.ini

Inside the .ini you will find a large number of configuration options. Make sure to at least edit those with an INSTALL comment. Make especially sure to insert a site specific session secret (beaker.session.secret) and to set the debug flag to false in production environments.

Once you have configured your .ini, run the following command to initialize the database schema and create a couple of default entities. 

 $ cd /opt/adhocracy
 $ paster setup-app example.ini

Among other things, this will create:

  • a default user called admin with the password password.
  • an Adhocracy instance named "Test Instance"
  • a site directory (in adhocracy.site.dir) and some template documents (see below). The site directory will be referenced as $SITE in the rest of this document (or "example", just to mess with you).

[edit] Development HTTP Server

Paste can start a simple, multithreaded HTTP server for testing purposes. The command for this is: 

 $ cd /opt/adhocracy
 $ paster serve example.ini

This will start a server and serve requests on port 5000, i.e. http://adhocracy.lan:5000/. Another nice feature of this server is its ability to reload when changes in the source files are registered. To enable this function, add the following argument: 

 $ cd /opt/adhocracy
 $ paster serve example.ini --reload

[edit] Testing and Building Documentation

Adhocracy includes both a set of tests and some package documentation. In order to run the tests execute the following command: 

 $ cd /opt/adhocracy
 $ nostetests

This will execute all available tests. If you want to execute specific tests, refer to the nose documentation.

Building the documentation is trivial as well (provided you have sphinx and GNU make installed): 

 $ cd /opt/adhocracy/doc
 $ make html

This will generate documentation in the HTML format within the doc/ folder.

[edit] Deployment

[edit] Site Customization

Sites are a mechanism to allow you to customize your install of Adhocracy. A site configuration can have custom CSS, html pages, logos and icons. After executing the setup-app command (see Configuration), a skeleton custom site has been created. It includes the following components:

  • Static info pages inside the $SITE/page subdirectory.
    • Static pages are named in the following pattern: NAME.LANGUAGE.html. This way, if a German user requests an Adhocracy page, the system will first check for a German version and, if necessary, fall back to the English page.
    • By default, Adhocracy uses the following pages: index, about, imprint and privacy. You can add other pages and link to them at http://example.com/page/example.html.
  • Custom CSS is included after the base CSS file and can be used to override layout details such as the color scheme. It is located at $SITE/static/style/site.css.
  • A logo file can be placed at $SITE/static/img/header_logo.png. The logo file should roughly match the original format at 220x60 pixels.

[edit] Deploying on Apache

For any serious amount of requests, you should use the Apache web server instead of the Python built-in HTTP server. The following will describe how to set up Adhocracy using mod_wsgi.

Debian users - try this: 

 # apt-get install libapache2-mod-wsgi
 # a2enmod wsgi
 # apache2ctl restart

Everyone else: check the mod_wsgi web page

mod_wsgi will require a single Python program file to handle any requests coming from the web server. This file will have to contain path references to the actual Adhocracy codebase. During setup, a template of the launcher script was copied to $SITE/site.wsgi. Please edit this file to match your current environment.

Having done that, create an Apache configuration file. The following could be used as a template for a virtual host configuration: 

 <VirtualHost *:80>
    ServerAdmin support@example.com
    ServerName  example.com
    ServerAlias *.example.com
    WSGIDaemonProcess adhocracy user=adhocracy group=adhocracy threads=25
    WSGIProcessGroup adhocracy
    WSGIPassAuthorization On
    WSGIScriptReloading On
    WSGIReloadMechanism Process
    WSGIScriptAlias / /opt/adhocracy/example/site.wsgi
    ErrorLog /var/www/apache2/adhocracy-error.log
    LogLevel debug
    CustomLog /var/www/apache2/adhocracy-access.log combined
    ServerSignature On
 </VirtualHost>

More info:

[edit] Queue consumer

If you're planning to use a message queue, you will need to run a queue consumer batch job. The job should simply run a HTTP GET request on the URL /_queue_process. A simple shell script doing this is provided at scripts/queue_process.sh. To run this script using the CRON daemon, add the following line to /etc/crontab (Assuming your host name is example.com and your HTTP server is running at port 80): 

 * * * * * nobody /opt/adhocracy/scripts/queue_process.sh example.com:80

This will execute the queue consumer every minute, a sensible interval for a notification message dispatch.

Retrieved from "http://wiki.liqd.net/Adhocracy/Installation/en"