[PATCH 03/11] docs: Rewrite documentation
Damien Lespiau
damien.lespiau at intel.com
Wed Aug 19 23:10:24 AEST 2015
On Tue, Jun 30, 2015 at 09:52:01AM +0100, Stephen Finucane wrote:
> 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>
Looks good to me, especially the prospect of publishing the resulting
docs.
Acked-by: Damien Lespiau <damien.lespiau at intel.com>
--
Damien
> ---
> 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
>
> _______________________________________________
> Patchwork mailing list
> Patchwork at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork
More information about the Patchwork
mailing list