wiki:InstallationInstructions
Last modified 15 months ago

Installation Instructions

Installing Adhocracy is a somewhat complicated process. The administrator should have at least some experience in dealing with Python packages, Unix shell commands, server configuration (for deployment purposes) and optionally, building packages from mercurial checkouts.

Preflight Entertainment

First, make sure the dependencies in SoftwareDependencies were satisfied.

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.

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,

  • either install the virtualenv package found in your system's package manager (on Debian based systems, run apt-get install virtualenv) and do 
$ su adhocracy
$ virtualenv /opt/adhocracy/env --setuptools
[gibberish]
$ source /opt/adhocracy/env/bin/activate
  • or, if your system doesn't have virtualenv pre-packaged, try this: 
$ easy_install virtualenv
[gibberish]
$ su adhocracy 
$ python virtualenv.py /opt/adhocracy/env --setuptools
[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.

Make sure you don't forget the --setuptools parameter as some distributions package virtualenv with a default of distribute which unfortunately has a  bug which makes it unusable in a virtualenv.

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 available. You can enable it by setting the adhocracy.instance setting in your config file (see below). Note that the required singleton instance will be created upon executing the setup-app command described later on.

Getting Adhocracy

If you're a developer (or just would like to checkout the source code from the mercurial repository), read DevelopmentHints instead of this part.

Adhocracy's source code is hosted on PyPI, so download the version of your choice from  http://pypi.python.org/pypi/adhocracy/ and unpack it. Then, run setup by typing 

$ python setup.py install

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

Running Adhocracy

For information on how to execute Adhocracy, see the following pages: