Inital commit
[patchwork] / docs / INSTALL
1 Deploying Patchwork
2
3 Patchwork uses the django framework - there is some background on deploying
4 django applications here:
5
6  http://www.djangobook.com/en/1.0/chapter20/
7
8 You'll need the following (applications used for patchwork development are
9 in brackets):
10
11   * A python interpreter
12   * djano
13   * A webserver (apache)
14   * mod_python or flup
15   * A database server (postgresql)
16
17 1. Database setup
18
19     At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
20     database servers. If you have any (positive or negative) experiences with
21     either, email me.
22
23     For the following commands, a $ prefix signifies that the command should be
24     entered at your shell prompt, and a > prefix signifies the commant-line
25     client for your sql server (psql or mysql)
26
27     Create a database for the system, add accounts for two system users: the
28     web user (the user that your web server runs as) and the mail user (the
29     user that your mail server runs as). On Ubuntu these are
30     www-data and nobody, respectively.
31
32       PostgreSQL:
33         createdb patchwork
34         createuser www-data
35         createuser nobody
36
37       MySQL:
38         $ mysql
39         > CREATE DATABASE 'patchwork';
40         > INSERT INTO user (Host, User) VALUES ('localhost', 'www-data');
41         > INSERT INTO user (Host, User) VALUES ('localhost', 'nobody');
42
43 2. Django setup
44
45         You'll need to customise apps/settings.py to suit your database, and
46         change the SECRET_KEY variable too. While you're there, change the
47         following to suit your installation:
48
49           ADMINS,
50           TIME_ZONE
51           LANGUAGE_CODE
52           MEDIA_ROOT
53
54         Then, get patchwork to create its tables in your configured database:
55
56          cd apps/
57          ./manage.py syncdb
58
59         And add privileges for your mail and web users:
60
61         Postgresql:
62           psql -f lib/sql/grant-all.sql patchwork
63
64
65 3. Apache setup
66
67 Example apache configuration files are in lib/apache/.
68
69 mod_python:
70
71         This should be the simpler of the two to set up. An example apache
72         configuration file is in:
73
74           lib/apache/patchwork.mod_python.conf
75
76         However, mod_python and mod_php may not work well together. So, if your
77         web server is used for serving php files, the fastcgi method may suit
78         instead.
79
80 fastcgi:
81
82         django has built-in support for fastcgi, which requires the
83         'flup' python module. An example configuration is in:
84
85           lib/apache/patchwork.fastcgi.conf
86
87         - this also requires the mod_rewrite apache module to be loaded.
88
89         Once you have apache set up, you can start the fastcgi server with:
90
91           cd /srv/patchwork/apps
92           ./manage.py runfcgi method=prefork \
93                               socket=/srv/patchwork/var/fcgi.sock \
94                               pidfile=/srv/patchwork/var/fcgi.pid
95
96 4. Configure patchwork
97     Now, you should be able to administer patchwork, by visiting the
98     URL:
99
100       http://your-host/admin/
101
102     You'll probably want to do the following:
103
104       * Set up your projects
105
106
107 5. Subscribe a local address to the mailing list
108
109      You will need an email address for patchwork to receive email on - for
110      example - patchwork@, and this address will need to be subscribed to the
111      list. Depending on the mailing list, you will probably need to confirm the
112      subscription - temporarily direct the alias to yourself to do this.
113
114 6. Setup your MTA to deliver mail to the parsemail script
115
116     Your MTA will need to deliver mail to the parsemail script in the email/
117     directory. (Note, do not use the parsemail.py script directly). Something
118     like this in /etc/aliases is suitable for postfix:
119
120       patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
121
122     You may need to customise the parsemail.sh script if you haven't installed
123     patchwork in /srv/patchwork.
124
125     Test that you can deliver a patch to this script:
126
127      sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
128
129
130 Some errors:
131
132 * __init__() got an unexpected keyword argument 'max_length'
133
134  - you're running an old version of django. If your distribution doesn't
135    provide a newer version, just download and extract django into
136    lib/python/django
137
138 * ERROR: permission denied for relation patchwork_...
139
140  - the user that patchwork is running as (ie, the user of the web-server)
141    doesn't have access to the patchwork tables in the database. Check that
142    your web-server user exists in the database, and that it has permissions
143    to the tables.