-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL.txt
83 lines (50 loc) · 4.89 KB
/
INSTALL.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
The following installation instructions are kept up-to-date at http://trac.adhocracy.cc/wiki/InstallationInstructions
= 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 http://trac.adhocracy.cc/wiki/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 [http://pypi.python.org/pypi/virtualenv 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 (http://bitbucket.org/tarek/distribute/issue/100/easy_install-u-distribute-errors-out-with) 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 [http://en.wikipedia.org/wiki/Wildcard_DNS_record 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:
* http://trac.adhocracy.cc/wiki/QueueProcessing is required both for development and deployment
* http://trac.adhocracy.cc/wiki/RunningAdhocracy for development
* http://trac.adhocracy.cc/wiki/DeploymentSetup for production sites