skip to navigation
skip to content

adhocracy 2.4.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. <http:"">`_ 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 <http:"" licenses="" agpl-3.0.html="">`_.

Source code hosting, bug tracking and planned feature discussion is done `on
GitHub <https:"" liqd="" adhocracy="">`_.

Communication also takes place on the `adhocracy-dev mailing list
<http:"" cgi-bin="" mailman="" listinfo="" adhocracy-dev="">`_.

Documentation is included in the source code and can be read online `on
readthedocs <http:"">`_.

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
<http:"" cgi-bin="" mailman="" listinfo="" adhocracy-dev="">`_.

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 <https:"" pypi="" zc.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.

In any case you will need the following MIME types in ``/etc/mime.types``::

# webfonts
application/x-font-woff woff
application/font-truetype ttf

# socialshareprivacy 1.5 language files
application/json lang

Automatic installation on debian, Ubuntu or Arch Linux with

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


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


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 ruby-dev

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 ..

Configure Adhocracy as desired

Create a custom buildout file and customize it as desired::

$ cp buildout buildout-my.cfg
$ vi buildout-my.cfg

Install and start Adhocracy

Run buildout:


$ bin/python
$ bin/buildout -c buildout-my.cfg

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
- 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


[buildout] extends = buildout\_development.cfg parts -= postgresql

Developer instructions

To use your own `fork <https:"" articles="" fork-a-repo="">`_
instead of the regular("upstream") adhocracy, use
`git remote <http:"" pub="" software="" scm="" git="" docs="" git-remote.html="">`_:


$ 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 <http:"" pub="" software="" scm="" git="" docs="" git-commit.html="">`_
`push <http:"" pub="" software="" scm="" git="" docs="" git-push.html="">`_
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 <https:"" articles="" using-pull-requests="">`_ to ask
the core developers to incorporate your changes.

Adhocracy Changelog

2.4.1 (2014-04-30)

Release 2.4.0 had two minor bugs which are fixed in this patch release.

Bug fixes:

- The 2.4.0 release notes contained an error - solr reindexing requires a -c

- Do not fail displaying error messages.

2.4.0 (2014-04-30)

This update requires some manual adjustments:

- The translation files (.mo) are no longer included in the repository.
Please run `bin/buildout install translations` to create them automatically.

- A Solr reindexing is necessary: `bin/paster index -c etc/adhocracy.ini`

- Due to a bug, some notifications failed to be created in the past. Please
run `bin/adhocpy scripts/ etc/adhocracy.ini` to
create the missing notifications.


- Allow to configure separate domains per instance. This does not yet invlove
single-sign-on between different domains. (#886)

- Improve error pages. (#884)

- Add description, events and milestones views for categories. They are mostly
useful for embedding. (#883)

- Add captcha verification. (#878)

- Scroll into view if needed after overlay resize. (#870)

- Solr-based milestone proposal pager (#865)

- Make maximum category long description length configurable. (#863)

- Add a new proposal sorting which is a combination of support and impact.

- Document adhocracy's mime type requirements. (#862)

- Document all settings in adhocracy.ini. (#857)

- Allow to configure default proposal sorting. (#860, #868)

- Responsive Search widget (#854)

- The translation files (.mo) are now built automatically when running
buildout. (#741)

- Show item count in a tooltip in tagcloud facet. (#851)

- Better handling of connection erros with the external navigation. (#848)

- Instance specific static pages (#845)

- Link to category pages from proposal and page sidebars. (#847, #850)

- Gitignore generated CSS. (#839)

- Distinct styling for different kinds of show-hide buttons. (#841)

- Hide old dates on event carousel. (#838)

Bug fixes:

- Add a workaround for a caching issue with proposal lists if the description
is displayed inline.

- Show 404 errors instead of blank pages on nonexistent instance subdomains.

- Avoid unnecessary requests on startup. (#882)

- Add missing documentation for upgrading an existing adhocracy installation
in UPGRADING.rst . (#879)

- Avoid uneccessary delegateable invalidation. This significantly improves the
performance of creation and update of proposals, norms and instances. (#876)

- Replace only specific message variables in mass messages. This avoids errors
when using {}. (#875)

- Allow global admins to send mass messages in hidden instances as well.

- Warn user about exposing her email address when creating a message. (#873)

- Fix multiple bugs in traverse_watchlist, which resulted in missing
notifications. (#871)

- Fix multiple small issues with mass messages. (#869)

- Don't query static pages in the same locale multiple times.

- Make sure badge impact is commited before proposal update. (#866)

- Fix some wrong redirects in badge management. (#831)

- Prevent moderators to elevate their permissions. (#840)

- Provide a fallback if `came_from` is missing in the velruse controller. (#853)

- Fix page/proposal title validation. (#849, #852)

- Various syntax fixes in INSTALL.rst, thanks to Rowan Thorpe (#843)

- Fix some issues with entity deletion. (#842, #846)

2.3.0 (2014-03-31)


- Add external StaticPage backend which can be used with the adhocracy.kotti
or the adhocracy.plone backend.

- Add Brazilian Portuguese translation, thanks to Fabiano Rocha. (#817)

- The permission for user badge management is now separated from user group
management. (#837)

- More work on responsive design. (#798)

- Enable sectionpages by default.

- Add script which allows to merge instances. (#806)

- Move mass message button to members list. (#822)

- Add preset "planning ideas". (#828)

- Allow to not show instance settings after instance create.

- Preview of a simple oEmbed API. (#795)

Bug fixes:

- Fix wrong redirect after badge management. (#831)

- Don't close overlay after badge management.

- Fix redirect after Velruse (Facebook) login. (#830)

- Fix warning if OpenID and Velruse login is disabled.

- Full width instance background. (#820)

- Fix certain links in overlays. (#816)

- Fix advanced settings for instance admins. (#821)

- Fix missing dependency in installation documentation.

- Fix register page.

2.2.1 (2014-03-21)


- Moderators can change the instance description and some other things by

- 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

- 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.

- 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

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

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

- Add container pages. These special norms act as containers of other norms.

- 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.

- 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.

- 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).

- 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.

- 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.  
File Type Py Version Uploaded on Size (md5) Source 2014-04-30 23MB