Patchwork uses the django framework - there is some background on deploying
django applications here:
- http://www.djangobook.com/en/1.0/chapter20/
+ http://www.djangobook.com/en/2.0/chapter12/
You'll need the following (applications used for patchwork development are
in brackets):
* A python interpreter
- * django
+ * django >= 1.5
* A webserver (apache)
* mod_python or flup
- * A database server (postgresql)
+ * A database server (postgresql, mysql)
+ * relevant python modules for the database server (e.g: python-mysqldb)
+
1. Database setup
either, email me.
For the following commands, a $ prefix signifies that the command should be
- entered at your shell prompt, and a > prefix signifies the commant-line
+ entered at your shell prompt, and a > prefix signifies the command-line
client for your sql server (psql or mysql)
Create a database for the system, add accounts for two system users: the
user that your mail server runs as). On Ubuntu these are
www-data and nobody, respectively.
- For PostgreSQL
+ As an alternative, you can use password-based login and a single database
+ account. This is described further down.
+
+ For PostgreSQL (ident-based)
$ createdb patchwork
$ createuser www-data
$ createuser nobody
- - postgres uses the standard UNIX authentication, so these users
- will only be accessible for processes running as the same username.
- This means that no passwords need to be set.
+ - postgres uses the standard UNIX authentication, so these users
+ will only be accessible for processes running as the same username.
+ This means that no passwords need to be set.
+
+ For PostgreSQL (password-based)
+
+ $ createuser -PE patchwork
+ $ createdb -O patchwork patchwork
+
+ Once that is done, you need to tell Django about the new Database
+ settings, using local_settings.py (see below) to override the defaults
+ in settings.py:
- For MySQL:
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.postgresql_psycopg2',
+ 'HOST': 'localhost',
+ 'PORT': '',
+ 'USER': 'patchwork',
+ 'PASSWORD': 'my_secret_password',
+ 'NAME': 'patchwork',
+ },
+ }
+
+ For MySQL:
$ mysql
- > CREATE DATABASE 'patchwork';
+ > CREATE DATABASE patchwork CHARACTER SET utf8;
> CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
> CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
+ Once that is done, you need to tell Django about the new Database
+ settings, using local_settings.py (see below) to override the defaults
+ in settings.py:
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ 'HOST': 'localhost',
+ 'PORT': '',
+ 'USER': 'patchwork',
+ 'PASSWORD': 'my_secret_password',
+ 'NAME': 'patchwork',
+ 'TEST_CHARSET': 'utf8',
+ },
+ }
+
+ TEST_CHARSET is used when creating tables for the test suite. Without
+ it, tests checking for the correct handling of non-ASCII characters
+ fail.
+
+
2. Django setup
- Set up some initial directories in the patchwork base directory:
+ Set up some initial directories in the patchwork base directory:
- mkdir -p lib/packages lib/python
+ mkdir -p lib/packages lib/python
- lib/packages is for stuff we'll download, lib/python is to add
- to our python path. We'll symlink python modules into lib/python.
+ lib/packages is for stuff we'll download; lib/python is to add
+ to our python path. We'll symlink python modules into lib/python.
- At the time of release, patchwork depends on django version 1.0 or
- later. Your distro probably provides this. If not, do a:
+ At the time of release, patchwork depends on django version 1.5 or
+ later. Your distro probably provides this. If not, do a:
- cd lib/packages
- svn checkout http://code.djangoproject.com/svn/django/tags/releases/1.2
- cd ../python
- ln -s ../packages/django/django ./django
+ cd lib/packages
+ git clone https://github.com/django/django.git -b stable/1.5.x
+ cd ../python
+ ln -s ../packages/django/django ./django
- We also use the django-registration infrastructure from
- http://bitbucket.org/ubernostrum/django-registration/. Your distro
- may provide the django-registration python module (in Ubuntu/Debian it's
- called 'python-django-registration'). If not, download the module
- and symlink it to lib/python/ :
+ The patchwork/settings/*.py files contain default settings for patchwork,
+ you'll need to configure settings for your own setup.
- cd lib/packages/
- hg clone http://bitbucket.org/ubernostrum/django-registration/
- cd ../python
- ln -s ../lib/packages/django-registration/registration ./registration
+ Rather than editing these files (which will cause conflicts when you
+ update the base patchwork code), create a file 'production.py', based on
+ the example:
- We also use some Javascript libraries:
+ cp patchwork/settings/production.example.py \
+ patchwork/settings/production.py
- cd lib/packages
- mkdir jquery
- cd jquery
- wget http://jqueryjs.googlecode.com/files/jquery-1.3.min.js
- wget http://www.isocra.com/articles/jquery.tablednd_0_5.js.zip
- unzip jquery.tablednd_0_5.js.zip jquery.tablednd_0_5.js
- cd ../../../htdocs/js/
- ln -s ../../lib/packages/jquery/jquery-1.3.min.js ./
- ln -s ../../lib/packages/jquery/jquery.tablednd_0_5.js ./
+ and override or add settings as necessary. You'll need to define the
+ following:
- The settings.py file contains default settings for patchwork, you'll
- need to configure settings for your own setup.
+ SECRET_KEY
+ ADMINS
+ DATABASES
+ TIME_ZONE
+ LANGUAGE_CODE
+ DEFAULT_FROM_EMAIL
+ NOTIFICATION_FROM_EMAIL
- Rather than edit settings.py, create a file 'local_settings.py', and
- override or add settings as necessary. You'll need to define the
- following:
+ You can generate the SECRET_KEY with the following python code:
- SECRET_KEY
- ADMINS
- TIME_ZONE
- LANGUAGE_CODE
+ import string, random
+ chars = string.letters + string.digits + string.punctuation
+ print repr("".join([random.choice(chars) for i in range(0,50)]))
- You can generate the SECRET_KEY with the following python code:
+ If you wish to enable the XML-RPC interface, add the following to
+ your local_settings.py file:
- import string, random
- chars = string.letters + string.digits + string.punctuation
- print repr("".join([random.choice(chars) for i in range(0,50)]))
+ ENABLE_XMLRPC = True
- If you have patchwork installed in somewhere other than /srv/patchwork,
- you'll also need to define:
+ Then, get patchwork to create its tables in your configured database:
- MEDIA_ROOT
- TEMPLATE_DIRS
+ PYTHONPATH=lib/python ./manage.py syncdb
- If you wish to enable the XML-RPC interface, add the following to
- your local_settings.py file:
+ and initialise the static content:
- ENABLE_XMLRPC = True
+ PYTHONPATH=lib/python ./manage.py collectstatic
- Then, get patchwork to create its tables in your configured database:
+ You'll also need to load the initial tags and states into the
+ patchwork database:
- cd apps/
- PYTHONPATH=../lib/python ./manage.py syncdb
+ PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states
- And add privileges for your mail and web users:
+ Finally, add privileges for your mail and web users. This is only needed if
+ you use the ident-based approach. If you use password-based database
+ authentication, you can skip this step.
- Postgresql:
- psql -f lib/sql/grant-all.postgres.sql patchwork
+ Postgresql:
+ psql -f lib/sql/grant-all.postgres.sql patchwork
- MySQL:
- mysql patchwork < lib/sql/grant-all.mysql.sql
+ MySQL:
+ mysql patchwork < lib/sql/grant-all.mysql.sql
3. Apache setup
-Example apache configuration files are in lib/apache/.
+ Example apache configuration files are in lib/apache2/.
+
+ wsgi:
+
+ django has built-in support for WSGI, which supersedes the fastcgi
+ handler. It is thus the preferred method to run patchwork.
+
+ The necessary configuration for Apache2 may be found in
+
+ lib/apache2/patchwork.wsgi.conf.
+
+ You will need to install/enable mod_wsgi for this to work:
+
+ a2enmod wsgi
+ apache2ctl restart
+
-mod_python:
+ mod_python:
- This should be the simpler of the two to set up. An example apache
- configuration file is in:
+ An example apache configuration file for mod_python is in:
- lib/apache/patchwork.mod_python.conf
+ lib/apache2/patchwork.mod_python.conf
- However, mod_python and mod_php may not work well together. So, if your
- web server is used for serving php files, the fastcgi method may suit
- instead.
+ However, mod_python and mod_php may not work well together. So, if your
+ web server is used for serving php files, the fastcgi method may suit
+ instead.
-fastcgi:
- django has built-in support for fastcgi, which requires the
- 'flup' python module. An example configuration is in:
+ fastcgi:
- lib/apache/patchwork.fastcgi.conf
+ django has built-in support for fastcgi, which requires the
+ 'flup' python module. An example configuration is in:
- - this also requires the mod_rewrite apache module to be loaded.
+ lib/apache2/patchwork.fastcgi.conf
- Once you have apache set up, you can start the fastcgi server with:
+ - this also requires the mod_rewrite apache module to be loaded.
+
+ Once you have apache set up, you can start the fastcgi server with:
+
+ cd /srv/patchwork/
+ ./manage.py runfcgi method=prefork \
+ socket=/srv/patchwork/var/fcgi.sock \
+ pidfile=/srv/patchwork/var/fcgi.pid
- cd /srv/patchwork/apps
- ./manage.py runfcgi method=prefork \
- socket=/srv/patchwork/var/fcgi.sock \
- pidfile=/srv/patchwork/var/fcgi.pid
4. Configure patchwork
Now, you should be able to administer patchwork, by visiting the
You'll probably want to do the following:
* Set up your projects
- * Configure your website address (in the Sites) section of the admin
+ * Configure your website address (in the Sites) section
+
5. Subscribe a local address to the mailing list
- You will need an email address for patchwork to receive email on - for
- example - patchwork@, and this address will need to be subscribed to the
- list. Depending on the mailing list, you will probably need to confirm the
- subscription - temporarily direct the alias to yourself to do this.
+ You will need an email address for patchwork to receive email on - for
+ example - patchwork@, and this address will need to be subscribed to the
+ list. Depending on the mailing list, you will probably need to confirm the
+ subscription - temporarily direct the alias to yourself to do this.
+
6. Setup your MTA to deliver mail to the parsemail script
directory. (Note, do not use the parsemail.py script directly). Something
like this in /etc/aliases is suitable for postfix:
- patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
+ patchwork: "|/srv/patchwork/patchwork/bin/parsemail.sh"
You may need to customise the parsemail.sh script if you haven't installed
patchwork in /srv/patchwork.
Test that you can deliver a patch to this script:
- sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
+ sudo -u nobody /srv/patchwork/patchwork/bin/parsemail.sh < mail
+
+
+7. Set up the patchwork cron script
+
+ Patchwork uses a cron script to clean up expired registrations, and
+ send notifications of patch changes (for projects with this enabled).
+
+ Something like this in your crontab should work:
+
+ # m h dom mon dow command
+ */10 * * * * cd patchwork; ./manage.py cron
+
+
+ - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
+ setting, which defaults to 10 minutes.
+
+
+8. Optional: Configure your VCS to automatically update patches
+
+ The tools directory of the patchwork distribution contains a file
+ named post-receive.hook which is an example git hook that can be
+ used to automatically update patches to the Accepted state when
+ corresponding comits are pushed via git.
+
+ To install this hook, simply copy it to the .git/hooks directory on
+ your server, name it post-receive, and make it executable.
+
+ This sample hook has support to update patches to different states
+ depending on which branch is being pushed to. See the STATE_MAP
+ setting in that file.
+
+ If you are using a system other than git, you can likely write a
+ similar hook using pwclient to update patch state. If you do write
+ one, please contribute it.
Some errors:
to the tables.
* pwclient fails for actions that require authentication, but a username
- and password is given int ~/.pwclient rc. Server reports "No authentication
+ and password is given in ~/.pwclientrc. Server reports "No authentication
credentials given".
- if you're using the FastCGI interface to apache, you'll need the
projects / patchwork / blobdiff