skip to navigation
skip to content

adhocracy 2.2.1

Policy drafting and decision-making web platform

Latest Version: 2.5.3



Adhocracy is a web based software tool which facilitates cooperative policy drafting, proposal discussion and decisions in distributed groups.

It is primarily developed by the Liquid Democracy e.V. as a platform to implement Liquid Democracy concepts, as well as to provide a simple and working general purpose online participation platform.


Adhocracy is mostly written in Python 2. It’s built on top of many free software projects, such as the Pylons web framework, the Solr search platform, Memcached, Redis, many Python libraries and more.


Adhocracy is known to run on current Linux systems, such as Debian Squeeze. It might run on FreeBSD or OS X, but this hasn’t been tested recently.

Installation is usually done through buildout or through an installer script for Debian based systems. In either case, read INSTALLATION.rst.


Adhocracy is openly developed as free software and distributed for the common good under the AGPLv3 license.

Source code hosting, bug tracking and planned feature discussion is done on GitHub.

Communication also takes place on the adhocracy-dev mailing list.

Documentation is included in the source code and can be read online on readthedocs.

We’re very open for contributions, please drop us a note on the mailing list or create a pull request on GitHub.


Community support is available through the adhocracy-dev mailing list.

Commercial support (installation, hosting, customization, training) is offered by the Liquid Democracy e.V. - you can reach us at info(at)liqd(dot)de.

Adhocracy installation

Adhocracy makes heavy use of buildout, a Python build tool. It downloads, configures and builds nearly all dependencies to create a repeatable and isolated environment. In addition it sets up the supervisord service manager, which allows to easily start and stop the services which Adhocracy needs to run:

  • adhocracy (http server that runs Adhocracy with Spawning/WSGI)
  • adhocracy_worker (background queue processing)
  • solr (searching)
  • memcached (key-value cache)
  • redis (internal messaging queue)

Adhocracy is known to work on all modern Linux distributions, but should also run on OS X and FreeBSD with minor modifications.

There are two supported ways of installing Adhocracy:

  • A fully automatic installation, which downloads and sets up everything, is available for Debian, Ubuntu and Arch Linux. This is basically a wrapper around buildout.
  • The manual installation, which directly uses the buildout commands.

Both are described in the following.

Automatic installation on debian, Ubuntu or Arch Linux with

On debian, Ubuntu, or Arch you can simply execute the following in a terminal:

wget -nv -O && sh

The script will use sudo to install the required dependencies, and install, set up, and start the required services.

Add -c hhu to install with the preconfiguration for HHU Düsseldorf.

Manual installation

## Preparations

Install required system packages (Debian Squeeze example):

$ sudo apt-get install gcc make build-essential bin86 unzip libpcre3-dev mercurial git libssl-dev libbz2-dev pkg-config
$ sudo apt-get install python python-setuptools
$ sudo apt-get install libsqlite3-dev postgresql-server-dev-9.1
$ sudo apt-get install openjdk-6-jre
$ sudo apt-get install ruby rubygems

To make the apache vhost config work run:

$ sudo apt-get install libapache2-mod-proxy-html
$ sudo a2enmod proxy proxy_http proxy_html

Check out Adhocracy:

$ git clone
$ cd adhocracy

$ git submodule init
$ git submodule update

## Setup an isolated python environment to run Adhocracy

To install Adhocracy you need python (2.6|2.7) with PIL (python imaging) but no other system-packages.

Compile python and PIL with the included python buildout:

$ cd python
$ python
$ bin/buildout
$ cd ..

## Install and start Adhocracy

Run buildout:

$ bin/python
$ bin/buildout

Start Adhocracy and dependent servers:

$ bin/supervisord

If you do not use the buildout to compile and start the database system (currently only possible for PostgreSQL, but disabled by default), you have to setup the Adhocracy database manually:

$ bin/paster setup-app etc/adhocracy.ini --name=content

Run Adhocracy

Start Adhocracy and all dependent servers:

$ bin/supervisord

Restart servers:

$ bin/supervisorctl reload

View the status of all servers:

$ bin/supervisorctl status

To start/stop one server:

$ bin/supervisorctl stop <name>

Start the Adhocracy server in foreground mode:

$ bin/supervisorctl stop adhocracy
$ bin/paster serve etc/adhocracy.ini

Buildout configuration

  • Read buildout_commmon.cfg and buildout_development.cfg to learn all buildout configuration options.

  • Customize buildout.cfg to change the domains, ports and server versions.

  • Instead of compiling all dependencies (postgres, solr,..) you can also use system packages.

  • Use your custom buildout file to remove the included files you do not need:

    [buildout] extends = buildout_development.cfg parts -= postgresql

Developer instructions

To use your own fork instead of the regular(“upstream”) adhocracy, use `git remote <>`_:

$ git remote -v
origin (fetch)
origin (push)
$ git remote add USERNAME
$ git push USERNAME

You can now execute git pull origin to update your local copy with new upstream changes. Use `commit <>`_ and `push <>`_ to record and publish your changes. As soon as you are confident that you have implemented a feature or corrected a bug, create a pull request to ask the core developers to incorporate your changes.

Adhocracy Changelog

2.2.1 (2014-03-21)


  • Moderators can change the instance description and some other things by default.
  • Instance overview now displays a button to the form where it can be edited for anyone with sufficient authorization.
  • Instance Settings now contain an embed code for the event carousel.
  • Several improvements concerning Facebook Login. (#813, #810)
  • Compass and SASS are updated to the latest versions. (#812)
  • Instance overview can be replaced by static pages. (#814)

Bug fixes:

  • Fix URL query parameter encoding. (#808)
  • Fix avatar for usernames with underscores. (#811)

2.2.0 (2014-03-19)


  • Facebook login (#807)
  • Admins can give other users the permission to edit and manage badges; moderators can edit and manage instances badges by default. (#805)
  • Clean up notification priorities and user interface for selecting a priority over which users will receive an email. (#804)
  • You can send a message to supporters/opponents/creators of proposals. (#679)
  • All messages are now available in the dashboard. (#801)
  • Allow to display instance logo as background image instead. (#793)
  • Allow instance admins to choose from multiple themes. (#791)
  • Add a profiling middleware for simple debugging. (#792)
  • Allow to display tag facet filter as tag cloud. (#799)
  • Prepare for responsive design. (Not all widgets have been converted yet) (#779, #780)
  • Add a event carousel widget. (#776, #794)
  • Allow to filter event stream by event type. (#776, #797)
  • Show abstract instead of truncate content in page tiles. (#777)
  • Add context variable “body_css_classes” to append context specific css classes to the body tag. The default classes are: * logged_in|not_logged_in, * instance_key_<key>, * global_nav_home|global_nav_instances, * added_static_content, * css_classes from the static pages backend. * instance-<instance_key> * controller-<controller_identifier> * area-<area_identifier> [joka] (#772)
  • Update proposal list design. (#773)
  • Update category page design to look more like the proposal list. (#774)

Bug fixes:

  • Rewrite internal links in overlays to point to overlays. (#571)
  • Avoid generic 403 error pages and display useful information instead. (#786)
  • Fix unicode issues with urlquote. (#782)
  • Strip markdown syntax on truncated texts. (#775)

2.1.3 (2014-02-21)


  • Adopt breadcrumbs if proposal tab is disabled and category pages are enabled (#768)
  • Hide dashboard instance chooser in single instance settings through instance.index permission. (#766)
  • Sort milestone select items by date. (#769)
  • Show milestone date in milestone select. (#770)
  • Make user max bio length configurable. (#771)

Bug fixes:

  • Fix broken solr connection with non-ascii characters (regression introduced in 2.1.2).
  • Fix broken registration (regression introduced in 2.1.2).
  • Fix build issues with non-ascii characters in scss files. (#761)
  • Fix flex based grid tiles in Safari. (#763)
  • Fix section page display issue with touch devices. (#764)

2.1.2 (2014-02-18)

This is mainly a bugfix release.


  • a11y: Updated js.socialshareprivacy to 1.5 permits keyboard navigation. (#755)
  • Sort instance member lists by member, not user age. (#750)
  • More configuration options for Shibboleth authentication.

Bug fixes:

  • Proper fallback on non-existant sort order entry. (#758)
  • Only display locally relevant user badges in event stream. (#754)
  • Remove user from member list after user left instance. (#753)
  • Fix instance selector in user profile. (#751)
  • Fix regression causing instance join to raise a 403 error.
  • Fix adding subcomments on touch devices. (#748)
  • Nicer display of grid tiles. (#757)
  • Fix editing of database backed static pages.

2.1.1 (2014-02-04)

This is a patch release which actually allows upgrading to 2.1.x with the instructions given below in the 2.1.0 sections. When upgrading from 2.0.0 to 2.1.x, simply jump to 2.1.1 directly by doing git checkout 2.1.1.


  • Make sure the src/adhocracy/alembic/versions directory actually exists in order to make bin/paster setup-app … work.
  • Update some dependencies.
  • Fix search box placeholder for instances with quotes in title. (#740)

2.1.0 (2014-02-04)

This upgrade only splits the SQLAlchemy-related changes from the 2.0.0 release in order to make sure all migrations are executed and the database remains in a consistent state.


  • Update SQLAlchemy from 0.7.10 to 0.9.1.
  • Switch from sqlalchemy-migrate to Alembic. (#219)

Upgrade instructions:

If you haven’t upgraded for a long time (say six months or more), it’s best to delete parts, eggs, python/python-2.7 and python/parts directories and rebuild everything according to INSTALLATION.rst.

In any case, don’t upgrade to 2.1.0 in one go, but upgrade to 2.0.0 first by running:

git checkout 2.0.0
bin/paster setup-app etc/adhocracy.ini --name=content

And upgrade to 2.1.0 in a second step:

git checkout 2.1.0
bin/paster setup-app etc/adhocracy.ini --name=content

This makes sure the remaining sqlalchemy-migration based migrations are executed in the first step, and the Alembic environment is initialized properly in the second step.

2.0.0 (2014-02-03)

  • Start doing releases using semantic versioning (#77). This release’s changelog contains many changes from the past two years, but rather incomplete.

  • Allow to list norms in a tiled fashion. (#714)

  • Add container pages. These special norms act as containers of other norms. (#709)

  • Proposal descriptions can now be shown directly in proposal lists. (#733)

  • It is now possible to translate the English source strings through Transifex as it is done in all other languages. In Transifex, the en_GB language is used as the “translated” English langauage in contrast to the “source” English langauage and doesn’t imply that british English shall be used. (#102)

  • Automatically crop and center uploaded images (logos etc) to the desired size. (#711)

  • Badges can now be managed in context. (#713)

  • Add images and long description texts to categories. Categories can now be listed and individually displayed, each showing all assigned proposals. (#695)

  • Added user import script. (#649)

  • We redesigned the instance settings. The most notable change is the added possibility to select presets on instance creation. (#680)

    The user import and massmessage services have been moved. They can be found on the members index and instance overview, respectively.

  • It is now possible to follow instances. (#655)

  • All milestones now must have a date. (#658)

  • Added installation option to freeze the complete installation. (#289)

  • It is possible to select whether other users can edit a proposal. We added an instance option to set the default value of that option. (#632)

  • a11y improvements.

  • Added replay notification script, which recreates notifications inside the database which would have been created before notifications were stored in the database. (#624)

  • We completely redesigned the user profile (#430) and dashboard (#429): User can upload an avatar now (#641) and view notifications online.

  • Email texts are now wrapped at 78 characters per line. Long links are preserved. (#593)

  • Added travis configuration which automatically builds Adhocracy using and runs the test suite.

  • It is now possible to assign user badges in user import. It is also possible to define additional variables which can be used in the welcome email.

  • Added an installation option to redirect to an instance instead of showing the front page. This is useful for single-instance installations. (#431)

  • New comment design.

  • Subnorms can now be displayed as sections. This way you can add a large document consisting of multiple sections and have each of these sections discussed separately.

  • It is now possible to show all open proposals in the proposal list of future milestones. For milestones in the past, this doesn’t have any effect. (#562)

    This will be used in the following scenario:

    • There’s regular (offline) board meetings. These are entered as milestones. During a meeting, the board shall work on as many of the highest rated, non-frozen proposals as time permits.
    • All covered proposals will be assigned to the respective milestone, marked as frozen and badged as “implemented” (or whatever).
    • All not covered proposals will be covered in successive meetings.
  • It is now possible to freeze single proposals. (#559)

  • Overlays have their own urls now, so you can link to them. (#553)

  • Add warning to users of unsupported browsers. (#111)

  • Better user settings layout. (#174)

  • Allow footer customization through static URLs. (#472)

  • Add custom “show more” markdown extension. (#120)

  • now has Fedora support

  • Refactor all CSS and some of the templates to make development and theming easier. We also switched to SCSS.

  • Added varnish reverse proxy [joka]

  • Readd bin/test to run tests (wrapper for py.test) [joka]

  • Update python from 2.7.4 to 2.7.5. Please rebuild python:

    • cd python
    • bin/buildout


  • Use pytest testrunner instead of nose. (#343)

  • Add shibboleth based authentication. (#359)

  • Allow to disable tutorials installation-wide. (#54)

  • Update buildout from 1.7 to 2.1.0 (#241). Rerun buildout with:

    bin/buildout -n

    If you have versions conflicts with distribute delete the old one:

    rm -r eggs/distribute..".


  • The default way to isolate your python environment is now to compile python and PIL now instead of using virtualenv:

    Upgrade manual installation:
    Checkout python buildout
    * git submodule init
    * git submodule update
    Compile python:
    * cd python
    * python && bin/buildout
    Reinstall Adhocracy:
    * cd ../
    * rm -rf eggs/*
    * bin/python
    * bin/buildout
    * rm -rf eggs/*
    * sh -u
    * sh -s
  • Add controversy sorting method to proposals. (#258)

  • Allow to hide voting lists from the UI. (#189)

  • Badges with thumbnails. (#191)

  • Option to disable registration. (#43)

  • Login via email address

  • Hierarchical categories. (#95)

  • Formatted norms. (#192)

  • Replace RabbitMQ/amqp with redis/rq (#220). This means that you have to provide a working redis instance if you want to use asyncronous jobs (highly recommended in production). The background process that processes the jobs is renamed from ‘background’ to ‘worker’. You can call it with bin/paster –plugin=adhocracy worker -c etc/adhocracy.ini

    Configuration changes:

    • dropped: adhocracy.amqp.* settings are not required anymore.
    • new: An IP address redis can bind to (not a hostname!)
    • new: adhocracy.redis.port: The port redis will open
    • new: adhocracy.redis.queue: The queue name
  • Mandatory email validation. (#142)

  • Invisible badges. (#116)

  • Instance-based user rating sorting. (#190)

  • Disallow multiple usernames with only case differences. (#171)

  • Dashboard style instance overview page. (#90)

  • Support path based instances instead of subdomain only. (#62)

  • Feedback instance pull in form. (#88)

  • Lamson mailserver dummy for development purposes.

  • Added facet search to the instance listing. The listing is based on solr now, please reindex. [joka]

  • Instances can have badges now. To create instance badges use the site-administration -> badges form. To assign badges use the instance listing. [joka]

  • New config option “” that accepts a whitespace seperated list of email address and blocks registrations with those. Dots will be stripped before the test (to catch gmail addresses where dots are ignored by gmail). [csenger]

  • New config option “adhocracy.listings.instance.sorting” that makes the sort options for the instance listing configurable. This possible values are: OLDEST, NEWEST, ACTIVITY and ALPHA. [csenger]

  • Permission change: When we test the ‘norm.create’ permission (permission to create Norms/Topics/Themen we do no longer restrict it to users who also have ‘instance.admin’. The main permission we check now is ‘page.create’.

    Please check the permission ‘page.create’ in your permission settings (<base_url>/admin -> Permissions). [csenger]

  • Give the users the option to permanently activate the twitter, facebook or google+ buttons. Save the setting in a wildcard subdomain cookie so it is valid across all instances.

    This requires a updated js.socialshareprivacy to work with our auth cookie. [csenger]

  • Add the possibility to overwrite templates in <>/templates directory (like it’s possible for static resources and static pages already. New templates there need a server restart to be picked up. [csenger]

  • Deliver (almost) all resources with fanstatic. [csenger]

  • Delegateables can have category badges. [joka]

  • Instances can have badges, they are only valid inside that instance. [joka]

  • Added option to set the smtp port. [joka]

  • Many bugfixes.

  • Many other unmentioned improvements.


  • Tooltips use jquery tools now. [joka]
  • Open helper link, login and register form with overlay. [joka]
  • Recaptcha support (disabled by default). [joka]
  • Proposals can have badgets #263. [joka]


  • Users can have badgets #214. [carsten]
  • Proposal listing with natural sort #212. [joka]

1.1 (2010-12-05)

  • Join “Goal” and “Implementation” pages on proposals.
  • Migrate from whoosh to solr.
  • Allow single-instance mode of operation.
  • Allow per-instance deactivation of norms.
  • Remove wiki from system.
  • Change from cron-initiated regular background processing. to continuous background queue polling process.
  • Add INSTALL.txt and CHANGES.txt.
  • Change from BSD license to AGPL-3.
  • Update to SQLAlchemy 0.6.
  • Many smaller bug fixes.

1.0 (2010-07-24)

  • Initial stable release.

Adhocracy is licensed under the GNU Affero General Public License, Version 3, which can be found in LICENSE.txt

Adhocracy is Copyright 2009, 2010, 2011, 2012, 2013, 2014 by

Friedrich Lindenberg Joscha Krutzki Carsten Senger Nicolas Dietrich Philipp Hagemeister Tobias Bengfort

and others. Check git history to get a list of all contributors.