diff options
| author | Stephen Finucane <stephen.finucane@intel.com> | 2015-08-21 15:32:07 +0100 |
|---|---|---|
| committer | Damien Lespiau <damien.lespiau@intel.com> | 2015-09-17 17:40:09 +0100 |
| commit | 808904d8a80c2b41234f2de9827ebcf67edcf227 (patch) | |
| tree | 305840c6400c02d14e4e1cc3fdd3e7f37678aa76 /docs/installation.md | |
| parent | c1c3f73c0a98996e1347353864e9367ac69edf33 (diff) | |
| download | patchwork-808904d8a80c2b41234f2de9827ebcf67edcf227.tar patchwork-808904d8a80c2b41234f2de9827ebcf67edcf227.tar.gz | |
docs: Rewrite documentation
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.
Acked-by: Damien Lespiau <damien.lespiau@intel.com>
Signed-off-by: Stephen Finucane <stephen.finucane@intel.com>
Signed-off-by: Damien Lespiau <damien.lespiau@intel.com>
Diffstat (limited to 'docs/installation.md')
| -rw-r--r-- | docs/installation.md | 290 |
1 files changed, 290 insertions, 0 deletions
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@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. |