[PATCH v2 03/16] docs: Rewrite documentation
Stephen Finucane
stephen.finucane at intel.com
Sat Aug 22 00:32:07 AEST 2015
The INSTALL and HACKING documents are an important guide for new
patchwork users and developers and should be as informative as
possible. A number of changes were needed to these documents owing
to the out-of-date or incomplete information they contained. These
changes include:
* Removing references to the dead mod_python/flup projects
* Adding references to Gunicorn+nginx, which a credible modern
alternative to Apache+mod_wsgi
* Providing explanatory links to concepts/tools like ident-based
authentication and tox
* Referencing the newer tools available to developers, like tox
and the 'requirements.txt' files
* Integration with mkdocs, with eye on eventual publishing of
documentation to ReadTheDocs or equivalent.
These changes result in a significant rewrite which should hopefully
lower the barrier to entry for people wishing to use or develop
patchwork.
Signed-off-by: Stephen Finucane <stephen.finucane at intel.com>
---
docs/HACKING | 69 -------
docs/INSTALL | 305 -------------------------------
docs/development.md | 95 ++++++++++
docs/index.md | 66 +++++++
docs/installation.md | 290 +++++++++++++++++++++++++++++
mkdocs.yml | 10 +
patchwork/settings/production.example.py | 2 +-
7 files changed, 462 insertions(+), 375 deletions(-)
delete mode 100644 docs/HACKING
delete mode 100644 docs/INSTALL
create mode 100644 docs/development.md
create mode 100644 docs/index.md
create mode 100644 docs/installation.md
create mode 100644 mkdocs.yml
diff --git a/docs/HACKING b/docs/HACKING
deleted file mode 100644
index c1b478e..0000000
--- a/docs/HACKING
+++ /dev/null
@@ -1,69 +0,0 @@
-== Using virtualenv
-
-It's always a good idea to use virtualenv to develop python software.
-
-1. Install pip, virtualenv (python-pip, python-virtualenv packages)
-
- Because we're going to recompile our dependencies, we'll also need
- development headers:
-
- - For the MySQL/MariaDB setups: mariadb-devel (Fedora), libmysqlclient-dev
- (Debian)
-
-2. Create a new virtual environement. Virtual environments are "instances" of
- your system python, without any of the extra python packages installed.
- Inside a virtual env, we'll just install the dependencies needed for
- patchwork and run it from there.
-
- Virtual envs are useful to develop and deploy patchwork against a "well
- known" set of dependencies. They can also be used to test patchwork against
- several versions of django, creating a separate virtual env per version.
-
- $ virtualenv django-1.7
-
- will create a virtual env called 'django-1.7' in eponymous directory.
-
-3. Activate a virtual environment
-
- $ sources django-1.7/bin/activate
- (django-1.7)$
-
- The shell prompt is preprended with the virtual env name.
-
-4. Install the required dependencies
-
- To ease this task, it's customary to maintain a list of dependencies in a
- text file and install them in one go. One can maintain such a list of
- dependencies per interesting configuration.
-
- (django-1.7)$ pip install -r docs/requirements-django-1.7-mysql.txt
-
- Of course, this is a one-time step, once installed in the virtual
- environment, no need to to install the requirements everytime.
-
-5. Now one can run patchwork within that environment
-
- (django-1.7)$ ./manage.py --version
- 1.7
- (django-1.7)$ ./manage.py runserver
-
-6. To exit the virtual environment
-
- (django-1.7)$ deactivate
- $
-
-
-== Running tests
-
-- To run all tests:
-
- $ ./manage.py test
-
-- To run all test methods (methods which name starts with 'test') of a TestCase
- subclass:
-
- $ ./manage.py test patchwork.tests.SubjectCleanUpTest
-
-- To run a single test:
-
- $ ./manage.py test patchwork.tests.SubjectCleanUpTest.testSubjectCleanup
diff --git a/docs/INSTALL b/docs/INSTALL
deleted file mode 100644
index bd95770..0000000
--- a/docs/INSTALL
+++ /dev/null
@@ -1,305 +0,0 @@
-Deploying Patchwork
-
-Patchwork uses the django framework - there is some background on deploying
-django applications here:
-
- 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 >= 1.5
- * A webserver (apache)
- * mod_python or flup
- * A database server (postgresql, mysql)
- * relevant python modules for the database server (e.g: python-mysqldb)
-
-
-1. Database setup
-
- At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
- database servers. If you have any (positive or negative) experiences with
- 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 command-line
- client for your sql server (psql or mysql)
-
- Create a database for the system, add accounts for two system users: the
- web user (the user that your web server runs as) and the mail user (the
- user that your mail server runs as). On Ubuntu these are
- www-data and nobody, respectively.
-
- 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.
-
- 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:
-
- 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 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:
-
- 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.
-
- 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
- git clone https://github.com/django/django.git -b stable/1.5.x
- cd ../python
- ln -s ../packages/django/django ./django
-
- The patchwork/settings/*.py files contain default settings for patchwork,
- you'll need to configure settings for your own setup.
-
- 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:
-
- cp patchwork/settings/production.example.py \
- patchwork/settings/production.py
-
- and override or add settings as necessary. You'll need to define the
- following:
-
- SECRET_KEY
- ADMINS
- DATABASES
- TIME_ZONE
- LANGUAGE_CODE
- DEFAULT_FROM_EMAIL
- NOTIFICATION_FROM_EMAIL
-
- You can generate the SECRET_KEY with the following python code:
-
- import string, random
- chars = string.letters + string.digits + string.punctuation
- print repr("".join([random.choice(chars) for i in range(0,50)]))
-
- If you wish to enable the XML-RPC interface, add the following to
- your local_settings.py file:
-
- ENABLE_XMLRPC = True
-
- Then, get patchwork to create its tables in your configured database:
-
- PYTHONPATH=lib/python ./manage.py syncdb
-
- and initialise the static content:
-
- PYTHONPATH=lib/python ./manage.py collectstatic
-
- You'll also need to load the initial tags and states into the
- patchwork database:
-
- PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states
-
- 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
-
- MySQL:
- mysql patchwork < lib/sql/grant-all.mysql.sql
-
-
-3. Apache setup
-
- 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:
-
- An example apache configuration file for mod_python is in:
-
- 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.
-
-
- fastcgi:
-
- django has built-in support for fastcgi, which requires the
- 'flup' python module. An example configuration is in:
-
- lib/apache2/patchwork.fastcgi.conf
-
- - 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
-
-
-4. Configure patchwork
- Now, you should be able to administer patchwork, by visiting the
- URL:
-
- http://your-host/admin/
-
- You'll probably want to do the following:
-
- * Set up your projects
- * 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.
-
-
-6. Setup your MTA to deliver mail to the parsemail script
-
- Your MTA will need to deliver mail to the parsemail script in the email/
- directory. (Note, do not use the parsemail.py script directly). Something
- like this in /etc/aliases is suitable for postfix:
-
- 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/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:
-
-* __init__() got an unexpected keyword argument 'max_length'
-
- - you're running an old version of django. If your distribution doesn't
- provide a newer version, just download and extract django into
- lib/python/django
-
-* ERROR: permission denied for relation patchwork_...
-
- - the user that patchwork is running as (ie, the user of the web-server)
- doesn't have access to the patchwork tables in the database. Check that
- your web-server user exists in the database, and that it has permissions
- to the tables.
-
-* pwclient fails for actions that require authentication, but a username
- 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
- '-pass-header Authorization' option to the FastCGIExternalServer
- configuration directive.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..a4eb321
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,95 @@
+# Developing patchwork
+
+## Using virtualenv
+
+It's a good idea to use virtualenv to develop Python software. Virtual
+environments are "instances" of your system Python, without any of the
+additional Python packages installed. They are useful to develop and deploy
+patchwork against a "well known" set of dependencies, but they can also be
+used to test patchwork against several versions of Django.
+
+1. Install pip, virtualenv (python-pip, python-virtualenv packages)
+
+ Because we're going to recompile our dependencies, we'll also need
+ development headers. For the MySQL/MariaDB setups these are
+ `mariadb-devel` (Fedora), `libmysqlclient-dev` (Debian)
+
+2. Create a new virtual environement.
+
+ Inside a virtual env, we'll just install the dependencies needed for
+ patchwork and run it from there.
+
+ $ virtualenv django-1.8
+
+ This will create a virtual env called 'django-1.8' in eponymous directory.
+
+3. Activate a virtual environment
+
+ $ source django-1.8/bin/activate
+ (django-1.8)$
+
+ The shell prompt is preprended with the virtual env name.
+
+4. Install the required dependencies
+
+ To ease this task, it's customary to maintain a list of dependencies in a
+ text file and install them in one go. One can maintain such a list of
+ dependencies per interesting configuration.
+
+ (django-1.8)$ pip install -r docs/requirements-dev.txt
+
+ You will also need to install a version of Django - we don't install this
+ by default to allow development against multiple versions of Django. This
+ can be installed like so (assuming Django 1.8):
+
+ (django-1.8)$ pip install 'django<1.9,>=1.8'
+
+ Of course, this is a one-time step: once installed in the virtual
+ environment there is no need to to install requirements again.
+
+5. Run the development server
+
+ (django-1.8)$ ./manage.py --version
+ 1.8
+ (django-1.8)$ ./manage.py runserver
+
+Once finished, you can kill the server (`Ctrl` + `C`) and exit the the virtual
+environment:
+
+ (django-1.8)$ deactivate
+ $
+
+Should you wish to re-enter this environment, simply source the `activate`
+script again.
+
+## Running Tests
+
+patchwork includes a [tox] script to automate testing. Before running this, you
+should probably install tox:
+
+ $ pip install tox
+
+You can show available
+targets like so:
+
+ $ tox --list
+
+You'll see that this includes a number of targets to run unit tests against the
+different versions of Django supported, along with some other targets related
+to code coverage and code quality. To run these, use the `-e` parameter:
+
+ $ tox -e py27-django18
+
+In the case of the unit tests targets, you can also run specific tests by
+passing the fully qualified test name as an additional argument to this
+command:
+
+ $ tox -e py27-django18 patchwork.tests.SubjectCleanUpTest
+
+Because patchwork support multiple versions of Django, it's very important
+that you test against all supported versions. When run without argument, tox
+will do this:
+
+ $ tox
+
+[tox]: https://tox.readthedocs.org/en/latest/
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..f79f84b
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,66 @@
+# patchwork
+
+patchwork is a patch tracking system for community-based projects. It is
+intended to make the patch management process easier for both the project's
+contributors and maintainers, leaving time for the more important (and more
+interesting) stuff.
+
+Patches that have been sent to a mailing list are 'caught' by the system, and
+appear on a web page. Any comments posted that reference the patch are appended
+to the patch page too. The project's maintainer can then scan through the list
+of patches, marking each with a certain state, such as Accepted, Rejected or
+Under Review. Old patches can be sent to the archive or deleted.
+
+Currently, patchwork is being used for a number of open-source projects, mostly
+subsystems of the Linux kernel. Although Patchwork has been developed with the
+kernel workflow in mind, the aim is to be flexible enough to suit the majority
+of community projects.
+
+# Download
+
+The latest version of Patchwork is available with git. To download:
+
+ $ git clone git://ozlabs.org/home/jk/git/patchwork
+
+Patchwork is distributed under the [GNU General Public License].
+
+# Design
+
+## patchwork should supplement mailing lists, not replace them
+
+Patchwork isn't intended to replace a community mailing list; that's why you
+can't comment on a patch in patchwork. If this were the case, then there would
+be two forums of discussion on patches, which fragments the patch review
+process. Developers who don't use patchwork would get left out of the
+discussion.
+
+However, a future development item for patchwork is to facilitate on-list
+commenting, by providing a "send a reply to the list" feature for logged-in
+users.
+
+## Don't pollute the project's changelogs with patchwork poop
+
+A project's changelogs are valuable - we don't want to add patchwork-specific
+metadata.
+
+## patchwork users shouldn't require a specific version control system
+
+Not everyone uses git for kernel development, and not everyone uses git for
+patchwork-tracked projects.
+
+It's still possible to hook other programs into patchwork, using the pwclient
+command-line client for patchwork, or directly to the XML RPC interface.
+
+# Getting Started
+
+You should check out the [installation] and [development] guides for
+information on how to get to work with patchwork.
+
+# Support
+
+All questions and contributions should be sent to the [patchwork mailing list].
+
+[GNU General Public License]: http://www.gnu.org/licenses/gpl-2.0.html
+[installation]: installation.md
+[development]: development.md
+[patchwork mailing list]: https://ozlabs.org/mailman/listinfo/patchwork
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..6847b61
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,290 @@
+# Deploying Patchwork
+
+Patchwork uses the Django framework - there is some background on deploying
+Django applications here:
+
+ 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] >= 1.6. The latest version is recommended
+ * A webserver and suitable WSGI plugin. Options include [Apache] with the
+ [mod_python] plugin, or [Gunicorn] with [nginx] as the proxy server
+ * A database server (PostgreSQL, MySQL)
+ * Relevant Python modules for the database server (see the various
+ [requirements.txt] files)
+
+[Django]: https://www.djangoproject.com/
+[Apache]: http://httpd.apache.org/
+[mod_python]: http://modpython.org/
+[Gunicorn]: http://gunicorn.org/
+[nginx]: http://nginx.org/
+[requirements.txt]: ./docs
+
+## Database Configuration
+
+Django's ORM support multiple database backends, though the majority of testing
+has been carried out with PostgreSQL and MySQL.
+
+We need to create a database for the system, add accounts for two system users:
+the web user (the user that your web server runs as) and the mail user (the
+user that your mail server runs as). On Ubuntu these are `www-data` and
+`nobody`, respectively.
+
+As an alternative, you can use password-based login and a single database
+account. This is described further down.
+
+**NOTE:** For the following commands, a `$` prefix signifies that the command
+should be entered at your shell prompt, and a `>` prefix signifies the
+command-line client for your SQL server (`psql` or `mysql`).
+
+### Install Packages
+
+If you don't already have MySQL installed, you'll need to do so now. For
+example, to install MySQL on RHEL:
+
+ $ sudo yum install mysql-server
+
+### Create Required Databases and Users
+
+#### PostgreSQL (ident-based)
+
+PostgreSQL support [ident-based authentication], which uses the standard UNIX
+authentication method as a backend. This means no database-specific passwords
+need to be set/used. Assuming you are using this form of authentication, you
+just need to create the relevant UNIX users and database:
+
+ $ createdb patchwork
+ $ createuser www-data
+ $ createuser nobody
+
+[ident-based authentication]: http://www.postgresql.org/docs/8.4/static/auth-methods.html#AUTH-IDENT
+
+#### PostgreSQL (password-based)
+
+If you are not using the ident-based authentication, you will need to create
+both a new database and a new database user:
+
+ $ createuser -PE patchwork
+ $ createdb -O patchwork patchwork
+
+#### MySQL
+
+ $ mysql
+ > CREATE DATABASE patchwork CHARACTER SET utf8;
+ > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
+ > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
+
+### Configure Settings
+
+Once that is done, you need to tell Django about the new database settings,
+by defining your own `production.py` settings file (see below). For PostgreSQL:
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.postgresql_psycopg2',
+ 'HOST': 'localhost',
+ 'PORT': '',
+ 'USER': 'patchwork',
+ 'PASSWORD': 'my_secret_password',
+ 'NAME': 'patchwork',
+ 'TEST_CHARSET': 'utf8',
+ },
+ }
+
+If you're using MySQL, only the `ENGINE` changes:
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ ...
+ },
+ }
+
+**NOTE:** `TEST_CHARSET` (`TEST/CHARSET` in Django >= 1.7) is used when
+creating tables for the test suite. Without it, tests checking for the correct
+handling of non-ASCII characters fail.
+
+## Django Setup
+
+### Configure Directories
+
+Set up some initial directories in the patchwork base directory:
+
+ 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`.
+
+At the time of release, patchwork depends on Django version 1.6 or later.
+Where possible, try to use the latest stable version (currently 1.8). Your
+distro probably provides this. If not, install it manually:
+
+ cd lib/packages
+ git clone https://github.com/django/django.git -b stable/1.8.x
+ cd ../python
+ ln -s ../packages/django/django ./django
+
+### Configure Settings
+
+You will also need to configure a [settings] file for Django. A
+[sample settings file] is provided, which defines default settings for
+patchwork. You'll need to configure settings for your own setup and save this
+as `production.py` (or override the `DJANGO_SETTINGS_MODULE` environment
+variable).
+
+ cp patchwork/settings/production.example.py \
+ patchwork/settings/production.py
+
+At the very minimum, the following settings need to be configured:
+
+ SECRET_KEY
+ ADMINS
+ TIME_ZONE
+ LANGUAGE_CODE
+ DEFAULT_FROM_EMAIL
+ NOTIFICATION_FROM_EMAIL
+
+You can generate the `SECRET_KEY` with the following python code:
+
+ import string, random
+ chars = string.letters + string.digits + string.punctuation
+ print repr("".join([random.choice(chars) for i in range(0,50)]))
+
+If you wish to enable the XML-RPC interface, add the following to the file:
+
+ ENABLE_XMLRPC = True
+
+### Configure Database Tables
+
+Then, get patchwork to create its tables in your configured database. For
+Django 1.6 and below:
+
+ PYTHONPATH=../lib/python ./manage.py syncdb
+
+For Django 1.7+:
+
+ PYTHONPATH=../lib/python ./manage.py migrate
+
+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.
+
+For Postgresql:
+
+ psql -f lib/sql/grant-all.postgres.sql patchwork
+
+For MySQL:
+
+ mysql patchwork < lib/sql/grant-all.mysql.sql
+
+### Other Tasks
+
+You will need to collect the static content into one location from which
+it can be served (by Apache or nginx, for example):
+
+ PYTHONPATH=lib/python ./manage.py collectstatic
+
+You'll also need to load the initial tags and states into the patchwork
+database:
+
+ PYTHONPATH=lib/python ./manage.py loaddata default_tags default_states
+
+[sample_settings_file]: ../patchwork/settings/production.example.py
+[settings]: https://docs.djangoproject.com/en/1.8/topics/settings/
+
+## Apache Setup
+
+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
+
+## Configure patchwork
+
+Now, you should be able to administer patchwork, by visiting the URL:
+
+ http://your-host/admin/
+
+You'll probably want to do the following:
+
+* Set up your projects
+* Configure your website address (in the Sites section of the admin)
+
+## Subscribe a Local Address to the Mailing List
+
+You will need an email address for patchwork to receive email on - for example
+- `patchwork at your-host`, 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.
+
+## Setup your MTA to Deliver Mail to the Parsemail Script
+
+Your MTA will need to deliver mail to the parsemail script in the
+email/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"
+
+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
+
+## 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.
+
+## (Optional) Configure your VCS to Automatically Update Patches
+
+The tools directory of the patchwork distribution contains a file named
+`post-receive.hook` which is a sample git hook that can be used to
+automatically update patches to the `Accepted` state when corresponding
+commits 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:
+
+* `ERROR: permission denied for relation patchwork_...`
+ The user that patchwork is running as (i.e. the user of the web-server)
+ doesn't have access to the patchwork tables in the database. Check that your
+ web server user exists in the database, and that it has permissions to the
+ tables.
+
+* pwclient fails for actions that require authentication, but a username
+and password is given int ~/.pwclient rc. Server reports "No authentication
+credentials given".
+ If you're using the FastCGI interface to apache, you'll need the
+ `-pass-header Authorization` option to the FastCGIExternalServer
+ configuration directive.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..ce60307
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,10 @@
+site_name: patchwork
+site_url: http://jk.ozlabs.org/projects/patchwork/
+site_description: patchwork - the web-based patch tracking system
+
+repo_url: git://ozlabs.org/home/jk/git/patchwork
+
+pages:
+ - Home: 'index.md'
+ - Installation: 'installation.md'
+ - Development: 'development.md'
diff --git a/patchwork/settings/production.example.py b/patchwork/settings/production.example.py
index fd0a1f6..7af79a7 100644
--- a/patchwork/settings/production.example.py
+++ b/patchwork/settings/production.example.py
@@ -50,7 +50,7 @@ DATABASES = {
}
#
-# Static files settings. Set this to the
+# Static files settings
# https://docs.djangoproject.com/en/1.7/ref/settings/#static-files
#
--
2.0.0
More information about the Patchwork
mailing list