3 Patchwork uses the Django framework - there is some background on deploying
4 Django applications here:
6 http://www.djangobook.com/en/2.0/chapter12/
8 You'll need the following (applications used for patchwork development are
11 * A Python interpreter
12 * [Django] >= 1.6. The latest version is recommended
13 * A webserver and suitable WSGI plugin. Options include [Apache] with the
14 [mod_python] plugin, or [Gunicorn] with [nginx] as the proxy server
15 * A database server (PostgreSQL, MySQL)
16 * Relevant Python modules for the database server (see the various
17 [requirements.txt] files)
19 [Django]: https://www.djangoproject.com/
20 [Apache]: http://httpd.apache.org/
21 [mod_python]: http://modpython.org/
22 [Gunicorn]: http://gunicorn.org/
23 [nginx]: http://nginx.org/
24 [requirements.txt]: ./docs
26 ## Database Configuration
28 Django's ORM support multiple database backends, though the majority of testing
29 has been carried out with PostgreSQL and MySQL.
31 We need to create a database for the system, add accounts for two system users:
32 the web user (the user that your web server runs as) and the mail user (the
33 user that your mail server runs as). On Ubuntu these are `www-data` and
34 `nobody`, respectively.
36 As an alternative, you can use password-based login and a single database
37 account. This is described further down.
39 **NOTE:** For the following commands, a `$` prefix signifies that the command
40 should be entered at your shell prompt, and a `>` prefix signifies the
41 command-line client for your SQL server (`psql` or `mysql`).
45 If you don't already have MySQL installed, you'll need to do so now. For
46 example, to install MySQL on RHEL:
48 $ sudo yum install mysql-server
50 ### Create Required Databases and Users
52 #### PostgreSQL (ident-based)
54 PostgreSQL support [ident-based authentication], which uses the standard UNIX
55 authentication method as a backend. This means no database-specific passwords
56 need to be set/used. Assuming you are using this form of authentication, you
57 just need to create the relevant UNIX users and database:
63 [ident-based authentication]: http://www.postgresql.org/docs/8.4/static/auth-methods.html#AUTH-IDENT
65 #### PostgreSQL (password-based)
67 If you are not using the ident-based authentication, you will need to create
68 both a new database and a new database user:
70 $ createuser -PE patchwork
71 $ createdb -O patchwork patchwork
76 > CREATE DATABASE patchwork CHARACTER SET utf8;
77 > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
78 > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
80 ### Configure Settings
82 Once that is done, you need to tell Django about the new database settings,
83 by defining your own `production.py` settings file (see below). For PostgreSQL:
87 'ENGINE': 'django.db.backends.postgresql_psycopg2',
91 'PASSWORD': 'my_secret_password',
93 'TEST_CHARSET': 'utf8',
97 If you're using MySQL, only the `ENGINE` changes:
101 'ENGINE': 'django.db.backends.mysql',
106 **NOTE:** `TEST_CHARSET` (`TEST/CHARSET` in Django >= 1.7) is used when
107 creating tables for the test suite. Without it, tests checking for the correct
108 handling of non-ASCII characters fail.
112 ### Configure Directories
114 Set up some initial directories in the patchwork base directory:
116 mkdir -p lib/packages lib/python
118 `lib/packages` is for stuff we'll download, `lib/python` is to add to our
119 Python path. We'll symlink Python modules into `lib/python`.
121 At the time of release, patchwork depends on Django version 1.6 or later.
122 Where possible, try to use the latest stable version (currently 1.8). Your
123 distro probably provides this. If not, install it manually:
126 git clone https://github.com/django/django.git -b stable/1.8.x
128 ln -s ../packages/django/django ./django
130 ### Configure Settings
132 You will also need to configure a [settings] file for Django. A
133 [sample settings file] is provided, which defines default settings for
134 patchwork. You'll need to configure settings for your own setup and save this
135 as `production.py` (or override the `DJANGO_SETTINGS_MODULE` environment
138 cp patchwork/settings/production.example.py \
139 patchwork/settings/production.py
141 At the very minimum, the following settings need to be configured:
148 NOTIFICATION_FROM_EMAIL
150 You can generate the `SECRET_KEY` with the following python code:
152 import string, random
153 chars = string.letters + string.digits + string.punctuation
154 print repr("".join([random.choice(chars) for i in range(0,50)]))
156 If you wish to enable the XML-RPC interface, add the following to the file:
160 ### Configure Database Tables
162 Then, get patchwork to create its tables in your configured database. For
163 Django 1.6 and below:
165 PYTHONPATH=../lib/python ./manage.py syncdb
169 PYTHONPATH=../lib/python ./manage.py migrate
171 Add privileges for your mail and web users. This is only needed if you use the
172 ident-based approach. If you use password-based database authentication, you
177 psql -f lib/sql/grant-all.postgres.sql patchwork
181 mysql patchwork < lib/sql/grant-all.mysql.sql
185 You will need to collect the static content into one location from which
186 it can be served (by Apache or nginx, for example):
188 PYTHONPATH=lib/python ./manage.py collectstatic
190 You'll also need to load the initial tags and states into the patchwork
193 PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states
195 [sample_settings_file]: ../patchwork/settings/production.example.py
196 [settings]: https://docs.djangoproject.com/en/1.8/topics/settings/
200 Example apache configuration files are in `lib/apache2/`.
204 django has built-in support for WSGI, which supersedes the fastcgi handler. It is thus the preferred method to run patchwork.
206 The necessary configuration for Apache2 may be found in:
208 lib/apache2/patchwork.wsgi.conf.
210 You will need to install/enable mod_wsgi for this to work:
215 ## Configure patchwork
217 Now, you should be able to administer patchwork, by visiting the URL:
219 http://your-host/admin/
221 You'll probably want to do the following:
223 * Set up your projects
224 * Configure your website address (in the Sites section of the admin)
226 ## Subscribe a Local Address to the Mailing List
228 You will need an email address for patchwork to receive email on - for example
229 - `patchwork@your-host`, and this address will need to be subscribed to the
230 list. Depending on the mailing list, you will probably need to confirm the
231 subscription - temporarily direct the alias to yourself to do this.
233 ## Setup your MTA to Deliver Mail to the Parsemail Script
235 Your MTA will need to deliver mail to the parsemail script in the
236 email/directory. (Note, do not use the `parsemail.py` script directly).
237 Something like this in /etc/aliases is suitable for postfix:
239 patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
241 You may need to customise the `parsemail.sh` script if you haven't installed
242 patchwork in `/srv/patchwork`.
244 Test that you can deliver a patch to this script:
246 sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
248 ## Set up the patchwork cron script
250 Patchwork uses a cron script to clean up expired registrations, and send
251 notifications of patch changes (for projects with this enabled). Something like
252 this in your crontab should work:
254 # m h dom mon dow command
255 */10 * * * * cd patchwork; ./manage.py cron
257 The frequency should be the same as the `NOTIFICATION_DELAY_MINUTES` setting,
258 which defaults to 10 minutes.
260 ## (Optional) Configure your VCS to Automatically Update Patches
262 The tools directory of the patchwork distribution contains a file named
263 `post-receive.hook` which is a sample git hook that can be used to
264 automatically update patches to the `Accepted` state when corresponding
265 commits are pushed via git.
267 To install this hook, simply copy it to the `.git/hooks` directory on your
268 server, name it `post-receive`, and make it executable.
270 This sample hook has support to update patches to different states depending
271 on which branch is being pushed to. See the `STATE_MAP` setting in that file.
273 If you are using a system other than git, you can likely write a similar hook
274 using `pwclient` to update patch state. If you do write one, please contribute
279 * `ERROR: permission denied for relation patchwork_...`
280 The user that patchwork is running as (i.e. the user of the web-server)
281 doesn't have access to the patchwork tables in the database. Check that your
282 web server user exists in the database, and that it has permissions to the
285 * pwclient fails for actions that require authentication, but a username
286 and password is given int ~/.pwclient rc. Server reports "No authentication
288 If you're using the FastCGI interface to apache, you'll need the
289 `-pass-header Authorization` option to the FastCGIExternalServer
290 configuration directive.